staff-mcp 2.0.1 → 2.0.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2.0.3 — 2026-10-26
+
+- Pin optional `node-pty` exactly to official prerelease `1.2.0-beta.18`, with Linux x64/arm64 N-API prebuilds for glibc >= 2.28. System libraries such as `libstdc++`/`libgcc` and an executable shell are still required; no user image upgrade or musl/Alpine terminal support is promised. Docker still mounts the host package/`node_modules`; normal-install prebuilt delivery does not eliminate build leftovers or platform mismatches.
+- Keep terminal off and native PTY unloaded by default. Explicit terminal requests now fail startup when platform/native/shell prerequisites are unavailable, including non-Linux Docker launchers and unsupported stdio Docker data topologies, rather than silently disabling terminal. Files degradation remains unchanged.
+- Send only responses to recognized standard MCP pings on a separate bounded POST lane; all other POSTs remain FIFO, with no replay, protocol version/flag change or timeout extension. Add queue-wait/POST-elapsed slow-send metadata diagnostics and host App resource-read timing/byte-count diagnostics, without tokens, URLs or bodies.
+- Upgrade the matching chat-ai host to commit `352bdb931bff38b5693dd386cd7584220571fd6b` or a descendant for stable App windows during loading/disconnection, cancellation and reopening cleanup, and accessible homepage close controls. These UI changes are delivered by chat-ai, not by the npm package. Extension protocol versions and data formats remain unchanged.
+
+## 2.0.2 — 2026-10-26
+
+- Report reverse control closure with fixed reasons, POST status/byte count/duration and bounded network error codes, without logging payloads, credentials or URLs. No retry/replay behavior changes.
+- Reuse workspace (`main`) and deduplicated allowed directories (`extra1`, `extra2`, …) for the optional file UI; explicit `-d` grants now appear there, with no automatic system-root authorization or separate Docker file-root mounts. Path, symlink, protected staging and write safety checks remain unchanged.
+- Remove `--file-root` / `ExtensionOptions.fileRoots` and `--shell` / `ExtensionOptions.shell`. PTY selects an executable absolute `$SHELL`, otherwise `/bin/bash`, preserving normal HOME and workspace cwd. Removed flags fail as unknown options; update launch configurations without a compatibility fallback.
+- Fix HTTP capacity internally at 64 sessions and remove MCP idle expiry, activity probes and `--http-max-sessions` / `--http-session-idle-ms` configuration. Pending startup and failed/pending cleanup still occupy capacity; DELETE, initialization failure, shutdown and data-session cleanup remain. Clients must close unused sessions. Child MCP limits/start/stop and reverse timeout defaults are unchanged.
+
 ## 2.0.1 — 2026-10-26
 
 - Resolve reverse data paths using the configured reverse origin, without requiring a public URL setting on chat-ai. Upgrade chat-ai and staff-mcp together; extension protocol versions remain v1.

package/README.md

@@ -10,14 +10,16 @@ It provides secure file management, shell execution, LSP-powered code intelligen
 
 ## Compatibility and coordinated upgrades
 
+**Version 2.0.3:** delivers Linux PTY prebuilds, reports explicit terminal startup failures, and prevents large reverse replies from blocking heartbeat responses. Upgrade chat-ai to commit `352bdb931bff38b5693dd386cd7584220571fd6b` or a descendant to also receive the App window lifecycle and close-control fixes.
+
 **Breaking release:** reverse connections and optional extensions require a matching chat-ai host: the host must implement reverse v1 and the session-relative data paths described below. Upgrade the host, staff-mcp, descriptors and UI assets together.
 
-Standard stdio/Streamable HTTP tools, resources and prompts remain supported. Extensions are **all off by default**; unavailable or incompatible optional capabilities must not break an otherwise healthy standard MCP connection. The old reverse handshake itself is incompatible, even with extensions disabled: extension degradation cannot replace the paired reverse upgrade. There is no old-protocol compatibility mode, automatic transfer resumption or input replay after disconnect.
+Standard stdio/Streamable HTTP tools, resources and prompts remain supported. Extensions are **all off by default**; optional discovery/data negotiation failures preserve an otherwise healthy standard MCP connection. Explicitly requesting terminal with unavailable platform/native/shell prerequisites fails startup instead of silently disabling it; files degradation is unchanged. The old reverse handshake itself is incompatible, even with extensions disabled: extension degradation cannot replace the paired reverse upgrade. There is no old-protocol compatibility mode, automatic transfer resumption or input replay after disconnect.
 
 No Chat8/schema9/format7/share protocol2 data migration is required.
 
 1. Finish in-flight operations and back up your normal configuration; no data conversion is needed.
-2. Upgrade the matching chat-ai host first, then staff-mcp 2.0.1, coordinating downtime for reverse connections.
+2. Upgrade the matching chat-ai host first, then staff-mcp 2.0.3, coordinating downtime for reverse connections.
 3. Reconnect MCP, reopen Apps and explicitly enable only the extensions you want.
 
 See [CHANGELOG](CHANGELOG.md) for the release summary.
@@ -26,22 +28,22 @@ See [CHANGELOG](CHANGELOG.md) for the release summary.
 
 Requires **Node.js 22.22.2 or newer**, including inside Docker images.
 
-Linux and Linux-host local Docker Engine are the primary full-extension environments, subject to the prerequisites below. Windows native standard MCP (stdio and HTTP) and Windows Docker standard MCP have been validated, not full extensions. Non-Linux Docker launchers disable optional extensions. **macOS has not been tested**; path translation is not a claim of platform support.
+Linux and Linux-host local Docker Engine are the primary full-extension environments, subject to the prerequisites below. Windows native standard MCP (stdio and HTTP) and Windows Docker standard MCP have been validated, not full extensions. Non-Linux Docker launchers reject an explicit terminal request; files-only requests retain warning-and-disable behavior. **macOS has not been tested**; path translation is not a claim of platform support.
 
-Run staff-mcp 2.0.1 with an explicit package version:
+Run staff-mcp 2.0.3 with an explicit package version:
 
 ```bash
-npx --yes staff-mcp@2.0.1 --working-dir /path/to/your/project
+npx --yes staff-mcp@2.0.3 --working-dir /path/to/your/project
 ```
 
-For a source checkout of staff-mcp 2.0.1, install dependencies and build before using the absolute entrypoint in the examples:
+For a source checkout, install dependencies and build before using the absolute entrypoint in the examples:
 
 ```bash
 npm ci
 npm run build
 ```
 
-Replace `/path/to/staff-mcp` with that checkout/build directory. Docker read-only mounts still require a compatible Node/native ABI/libc; in particular an optional PTY built for a different system is not guaranteed to work inside the image.
+Replace `/path/to/staff-mcp` with that checkout/build directory. Docker still read-only mounts the host package and `node_modules`, not an isolated container dependency installation. Version 2.0.3 pins optional `node-pty` exactly to the official prerelease `1.2.0-beta.18`, which includes N-API prebuilds for Linux x64/arm64 with glibc >= 2.28. The runtime still needs system libraries such as `libstdc++` and `libgcc`. This addresses prebuilt delivery for normal installs, not arbitrary local build leftovers or architecture/libc/platform mismatches; N-API does not remove those limits. No user image is upgraded automatically; terminal support is not promised for musl/Alpine.
 
 ### 1. Standard Host Mode
 Run directly on your physical machine or virtual environment.
@@ -50,10 +52,10 @@ node /path/to/staff-mcp/dist/src/index.js --working-dir /path/to/your/project
 ```
 
 ### 2. Docker Transparent Proxy Mode (Cyber-Shell)
-Run staff-mcp inside a compatible Docker image while keeping standard MCP control connected to the host. The wrapper mounts the project and package; image startup, Node/native ABI/libc and mount permissions still apply. Linux host + local Docker Engine is the full-extension path. Non-Linux Docker launchers disable optional Apps/files/terminal extensions with a warning; Windows Docker standard MCP has been validated, while macOS is untested; base Docker connectivity still requires a reachable daemon and valid bind mounts.
+Run staff-mcp inside a compatible Docker image while keeping standard MCP control connected to the host. The wrapper mounts the project and package; image startup, Node/native ABI/libc and mount permissions still apply. Linux host + local Docker Engine is the full-extension path. Non-Linux Docker launchers fail an explicit terminal request; files-only requests still warn and disable the optional extension; Windows Docker standard MCP has been validated, while macOS is untested; base Docker connectivity still requires a reachable daemon and valid bind mounts.
 
 ```bash
-# Debug a Node.js project inside a pure Alpine container
+# Standard MCP only, no terminal: debug inside an Alpine container
 node /path/to/staff-mcp/dist/src/index.js --docker node:22-alpine
 
 # Perform security analysis inside a custom reverse-engineering image
@@ -79,7 +81,7 @@ Add the following to your `claude_desktop_config.json`:
 ```
 
 ### 4. Reverse MCP Mode (Intranet Penetration)
-Connect outward from behind NAT/firewalls to chat-ai's existing Web entrypoint, without an inbound listener on staff. Control uses SSE + POST; remote-initiated raw HTTP GET/PUT carries file/terminal bytes on that same Web port. chat-ai provides the current session data path, which staff resolves against the existing `--ru` origin; `MCP_REVERSE_URL` is only an optional connection hint on chat-ai, not a data-channel prerequisite. Reconnect creates fresh sessions and never replays tool calls, transfer handles or terminal input.
+Connect outward from behind NAT/firewalls to chat-ai's existing Web entrypoint, without an inbound listener on staff. Control uses SSE + POST; remote-initiated raw HTTP GET/PUT carries file/terminal bytes on that same Web port. chat-ai provides the current session data path, which staff resolves against the existing `--ru` origin; no public-origin environment variable on chat-ai is required. Reconnect creates fresh sessions and never replays tool calls, transfer handles or terminal input.
 
 ```bash
 node /path/to/staff-mcp/dist/src/index.js -t reverse \
@@ -128,6 +130,8 @@ The authoritative custom protocol is `chat-ai/docs/protocol/README.md` at the co
 
 Reverse GETs `<base>/sse` with `Authorization: Bearer <token>` and `X-MCP-Server-Name`; an SSE endpoint event supplies the POST message URL. SSE message events contain ordinary MCP JSON-RPC, not a private envelope. Explicit HTTP and HTTPS are accepted; HTTP logs one plaintext warning per start and does not protect tokens or payloads. Use HTTPS on untrusted networks; HTTPS verifies CA and target identity without automatic downgrade. The configured base URL has no credentials, query or fragment. No WebSocket upgrade, gateway process, launcher or private host leg is required. SDK initialization, data-session readiness and current user authorization remain separate checks; short-lived connections do not reset exponential backoff.
 
+Only responses to recognized inbound standard MCP `ping` requests use a separate bounded POST send lane. All other POSTs remain FIFO; no request/input replay, protocol version change or extra flag is added, and timeouts are not extended. Slow-send diagnostics distinguish queue wait from POST elapsed time using metadata only, never tokens, URLs or bodies. The host also records App resource-read timing and byte-count metadata.
+
 Optional CLI timeouts (milliseconds, forwarded in Docker mode):
 
 - `--reverse-connect-timeout`: 15000; 0 disables only the SSE connection deadline.
@@ -141,21 +145,25 @@ The two reverse transport sources (`src/reverse/SseTransport.ts` and chat-ai's `
 
 ## 🛠️ Core Capabilities
 
+The runtime behavior below applies to staff-mcp 2.0.3; extensions remain opt-in.
+
 Extensions are **all off by default**. Use `--extensions files`, `--extensions terminal`, or `--extensions files,terminal`; apps/data dependencies and terminal's streams v1 manifest are added automatically, not selected separately. Disabled features advertise no manifest entry and register no corresponding UI Resource or business handler. With both off there is no extension manifest or application data listener/session; ordinary MCP tools and non-UI Resources remain. HTTP mode still opens its normal MCP listener.
 
 ```bash
 # Files only, with the default main root at --working-dir
 node /path/to/staff-mcp/dist/src/index.js --extensions files -w /workspace
 # Terminal only; does not enable the file app
-node /path/to/staff-mcp/dist/src/index.js --extensions terminal --shell /bin/bash
-# Both apps, with explicit file roots replacing the default main root
+node /path/to/staff-mcp/dist/src/index.js --extensions terminal
+# Both apps; explicitly authorize assets for tools and the file app
 node /path/to/staff-mcp/dist/src/index.js --extensions files,terminal -w /workspace \
-  --file-root main=/workspace --file-root assets=/srv/assets
-# Explicit full-filesystem file access on a suitable Linux host (not a default)
-node /path/to/staff-mcp/dist/src/index.js --extensions files --file-root system=/
+  -d /srv/assets
+# Explicit full-filesystem authorization for tools and files on a suitable Linux host (not a default)
+node /path/to/staff-mcp/dist/src/index.js --extensions files -d /
 ```
 
-`--file-root id=path` may repeat; IDs must be unique lowercase letters/digits/hyphens, and relative paths resolve from the launching process cwd. Explicit roots replace, rather than append to, the default `main`. They affect the file app and its standard file Resources only when files is enabled, not the standard tools' `--working-dir` / `--allowed-dir` scope or terminal's default workspace cwd. Selecting `/` explicitly exposes the filesystem visible to the staff identity; it does not elevate privileges or create an OS security boundary. The library accepts [`ExtensionOptions`](src/extensions/config.ts): `{enabled?:('files'|'terminal')[],fileRoots?:{rootId:string,directory:string}[],shell?:string}`, with `enabled` defaulting to `[]`.
+With files enabled, roots reuse the standard tool authorization: `main` is `--working-dir`, followed by the resolved, deduplicated `--allowed-dir` directories in order as `extra1`, `extra2`, etc. Explicit `-d` authorization is therefore visible in the file UI as well as tools; no system root is added automatically. Relative directories resolve from the launching process cwd. `-d /` explicitly authorizes the filesystem visible to staff for both tools and files, subject to OS permissions; it grants no OS privileges or shell sandbox. The library accepts [`ExtensionOptions`](src/extensions/config.ts): `{enabled?:('files'|'terminal')[]}`, with `enabled` defaulting to `[]`.
+
+`--file-root`, `--shell`, `--http-max-sessions` and `--http-session-idle-ms` have been removed and now fail as unknown options. Remove them from launch configurations; use `-w` / `-d` for file authorization and the normal `SHELL` environment for shell selection. There is no compatibility fallback.
 
 ### Independent file workspace
 
@@ -165,7 +173,7 @@ New Apps reusing supported RPC/Resources, files or streams need only their own d
 
 ### Human terminal (explicit extension opt-in)
 
-`--extensions terminal` needs Linux, a loadable optional `node-pty`, an executable shell and negotiated streams/data v1 with a usable duplex dataSession over local stdio/Docker, direct HTTP or reverse. If Linux/native PTY/shell requirements are unavailable, staff warns on stderr and omits terminal/streams from discovery; standard MCP and an available files extension remain usable. The default disabled state never loads the native PTY. `--shell` accepts an absolute executable path; otherwise a valid absolute executable `$SHELL` is used, falling back to `/bin/bash`. The interactive shell honors normal startup files and inherits staff's environment except exact internal control keys documented in the [terminal contract](docs/terminal.md). chat-ai uses the existing current-chat MCP grant and same-origin browser requests, with no extra terminal permission switch or high-risk confirmation. Terminal follows the host site's HTTP/HTTPS deployment policy without a terminal-specific TLS gate or origin allowlist. HTTPS is recommended for the entire site to protect login sessions, tool calls and terminal traffic; allowing HTTP does not encrypt those requests.
+`--extensions terminal` needs Linux, a loadable optional `node-pty`, an executable shell and negotiated streams/data v1 with a usable duplex dataSession over local stdio/Docker, direct HTTP or reverse. Unavailable Linux/native PTY/shell prerequisites make an explicit terminal request fail startup with an error, including when files is also requested; terminal is not silently omitted. The default disabled state never loads the native PTY. A valid absolute executable `$SHELL` is used, otherwise `/bin/bash`; if that is unavailable, the explicit terminal request fails startup, without another shell fallback. The interactive shell honors normal startup files and inherits staff's environment, including normal `HOME`, except exact internal control keys documented in the [terminal contract](docs/terminal.md). chat-ai uses the existing current-chat MCP grant and same-origin browser requests, with no extra terminal permission switch or high-risk confirmation. Terminal follows the host site's HTTP/HTTPS deployment policy without a terminal-specific TLS gate or origin allowlist. HTTPS is recommended for the entire site to protect login sessions, tool calls and terminal traffic; allowing HTTP does not encrypt those requests.
 
 The PTY starts at the staff workspace (`main`) by default, independently of file roots, and runs as the staff process uid: its starting root/cwd is **not a sandbox** and shell filesystem/network effects are not restricted by file-tool path checks. Terminal bytes never enter model context or chat history. Each stream uses one same-origin browser-to-chat-ai WebSocket at `/api/mcp/app-stream` (`chat-app-stream-v1`) for input, output, resize, presence and real xterm consumption ACKs. The backend remains the shared HTTP dataSession. Browser presence refreshes every 10 seconds with a separate 120-second host deadline; the host generic stream module schedules remote renewal from each returned lease (staff defaults to 30 seconds). Opening the Shell App starts one PTY without another open button or confirmation. Exit, PTY failure or disconnection leaves the app shell for manual reconnect; ordinary hidden views keep read/ACK/presence but reject new input and resize. Actual page exit, close, revocation or expiry cleans up; descendant cleanup is best effort, not rollback.
 
@@ -179,17 +187,19 @@ Never pollute your host machine again. By simply appending `--docker <image>`, `
 - Automatically translates Windows/Mac paths to Linux container paths.
 - Names containers after their launch context (e.g. `staff-mcp-myproj-3000-a1b2c3` = workspace `myproj`, HTTP port `3000`, random suffix `a1b2c3`), so multiple sessions are easy to tell apart in `docker ps`.
 - Mounts a dedicated Docker tools cache (`<staff-global>/tools/docker`) at `/opt/.staff/tools`, alongside the existing skills/profiles mounts. A matching non-root uid can write tools without creating directories in the image, and container-installed tools do not overwrite the host tool cache. Existing mount permissions still apply; no automatic chown or chmod.
-- Allows `--docker-args` for compatible hardware/environment settings (e.g., ADB USB debugging or GPUs). Unsupported stdio data topologies disable optional extensions, not the MCP control connection; overrides of managed bootstrap/mapping and container lifecycle controls remain errors.
+- Allows `--docker-args` for compatible hardware/environment settings (e.g., ADB USB debugging or GPUs). Unsupported stdio data topologies fail an explicit terminal request; files-only requests retain optional-extension degradation; overrides of managed bootstrap/mapping and container lifecycle controls remain errors.
 
 For **supported Linux local Docker stdio with at least one effective extension enabled**, the existing wrapper reserves a private container port published to a random **127.0.0.1** host port and inspects only its own cidfile container. A read-only mount of a host **0600 metadata file** supplies the reachable base URL without rewriting stdin/stdout or asking users to discover container IPs. The application listener remains lazy until `data/v1/configure`. With all extensions off, `dataAuto` is false: no application-data port publication, metadata mount or bootstrap is created. Ordinary workspace/package mounts are unchanged. Non-Docker stdio also has no application listener before configure. HTTP/reverse add no such publication; disabled extensions create no dataSession, while HTTP retains its MCP listener.
 
-When files is enabled, each explicit Docker `--file-root id=path` bind-mounts that host path at `/opt/staff-file-roots/<id>`. Thus `--file-root system=/` explicitly binds the host root there, rather than referring only to the container root. This is a deliberate wide filesystem exposure, not automatic host privilege acquisition or a claim of support across all platforms; actual OS/container permissions and Docker topology still apply. Default file `main` and terminal cwd use the existing workspace mount.
+Docker files reuse only the existing workspace (`/workspace`, root `main`) and allowed-directory bind mounts; no separate file-root mounts are created. Explicit `-d /` is deliberately broad host access through the allowed-directory mapping, subject to Docker/OS permissions and topology. Terminal cwd stays `/workspace`, independent of extra roots.
+
+Docker reuses the allowed-directory mounts for both tools and the file UI. A host filesystem root such as `/` is mapped to `/opt/staff-allowed/root-N` because Docker forbids mounting onto container `/`; the inner `-d` and protected staging aliases use the mapped path.
 
-This application-data path requires a local daemon and the host client/wrapper sharing reachable loopback, with compatible bridge/port publication. Non-Linux Docker launchers and incompatible stdio data topologies (remote/TCP/SSH daemon or host/container networking) warn and omit optional extensions; they retain ordinary MCP control/tools when Docker itself can start. HTTP/reverse do not need this stdio mapping. A failed data bootstrap or unavailable data configuration must not terminate an otherwise healthy MCP connection: data-dependent Apps stay unavailable, with no legacy byte fallback or operation replay. Loopback publication is not isolation from hostile containers. Metadata stays 0600 and must be readable by the container uid; workspace/global-directory permissions and PTY ABI/libc still apply. No automatic chown, permission relaxation or browser-user identity switch is performed. Normal exit/signals still clean the owned container, publication and metadata; no cross-restart resource recovery is promised.
+This application-data path requires a local daemon and the host client/wrapper sharing reachable loopback, with compatible bridge/port publication. Non-Linux Docker launchers and incompatible stdio data topologies (remote/TCP/SSH daemon or host/container networking) fail an explicit terminal request. Without terminal requested, files retains warning-and-disable degradation and ordinary MCP control/tools remain when Docker itself can start. HTTP/reverse do not need this stdio mapping. A failed data bootstrap or unavailable data configuration must not terminate an otherwise healthy MCP connection: data-dependent Apps stay unavailable, with no legacy byte fallback or operation replay. Loopback publication is not isolation from hostile containers. Metadata stays 0600 and must be readable by the container uid; workspace/global-directory permissions and PTY ABI/libc still apply. No automatic chown, permission relaxation or browser-user identity switch is performed. Normal exit/signals still clean the owned container, publication and metadata; no cross-restart resource recovery is promised.
 
-### Optional extensions do not define MCP connectivity
+### Optional negotiation failures versus explicit terminal startup errors
 
-Availability is determined separately for files, terminal and the per-connection data channel. A missing terminal runtime disables terminal only; an unavailable configured file root disables the optional file extension while preserving the standard workspace tools/resources. Unknown or incompatible extension versions do not enable their handlers or Apps. chat-ai keeps successfully initialized standard tools/resources/prompts if optional Apps discovery or data configuration fails. Warnings go to stderr, never stdio JSON-RPC stdout.
+Availability is determined separately for files, terminal and the per-connection data channel. A missing terminal runtime fails startup only when terminal is explicitly requested; with terminal disabled no native PTY is loaded. An unavailable configured file root still disables the optional file extension while preserving the standard workspace tools/resources. Unknown or incompatible extension versions do not enable their handlers or Apps. chat-ai keeps successfully initialized standard tools/resources/prompts if optional Apps discovery or data configuration fails. Warnings go to stderr, never stdio JSON-RPC stdout.
 
 This is not an authentication or lifecycle bypass: malformed CLI arguments, Docker launch failure, invalid credentials, and failed standard MCP transport/initialization remain errors. Workspace/global-mount access errors still fail the affected startup or file/tool operation; optional-extension degradation does not grant access or promise that every directory is prevalidated. Old/new incompatible reverse control protocols still require paired upgrades; optional capability degradation does not make those wire protocols compatible. No failed or uncertain file commit/tool/terminal input is automatically retried.
 
@@ -214,27 +224,17 @@ node /path/to/staff-mcp/dist/src/index.js --profile default
 node /path/to/staff-mcp/dist/src/index.js --profile android-reverse
 ```
 
-### HTTP session capacity and idle expiry
-
-Each HTTP listener admits at most **64 sessions** by default. Starting sessions and sessions whose cleanup is still pending or failed count toward that limit. A full listener returns HTTP **429** for new initialization without evicting an existing session; successful cleanup frees the slot. Use `--http-max-sessions <positive integer>` to configure it. This is independent of `--max-mcp-sessions`, which limits managed child MCP servers.
+### HTTP session capacity and lifetime
 
-An HTTP session becomes eligible for cleanup after **30 minutes of observed inactivity** (`--http-session-idle-ms <milliseconds>`, 1..2147483647). A single sweep runs at most once per minute (or at the shorter configured timeout). A valid incoming MCP control message restarts the idle grace. Idle GET/SSE connections, server notifications, invalid HTTP requests and unauthenticated data attempts do not keep a session alive.
+Each HTTP listener admits at most **64 sessions**, a fixed internal limit. Starting sessions and sessions whose cleanup is still pending or failed count toward that limit. A full listener returns HTTP **429** for new initialization without evicting an existing session; successful cleanup frees the slot. This is independent of `--max-mcp-sessions`, which still limits managed child MCP servers and retains explicit start/stop.
 
-Running request handlers (even after HTTP disconnect/cancellation), file preparation/valid leases/in-flight writes or commits, pending data setup/open channels, and owned PTYs or output/exit draining prevent idle eviction. These facts come from their existing owners; the idle policy does not renew business leases or equate cancellation with completion. After activity settles, the next idle observation starts a full grace interval. Completed result records and an empty configured data session alone do not pin the connection.
-
-An expired session ID returns HTTP **404**, including with an initialize body. Reconnect explicitly without the old ID; no tool, file commit or terminal input is replayed. Keeping an App iframe or an unsaved browser draft open does not pin an otherwise inactive server connection. The draft stays client-owned, but server operations require a new connection/App after expiry. This timeout applies only to HTTP listener sessions, not stdio or reverse. Docker HTTP forwards both flags. It is not a global quota for process-owned background commands, nested MCP sessions or LSP servers, and genuinely unsettled work/failed cleanup can continue occupying a slot.
-
-```bash
-node /path/to/staff-mcp/dist/src/index.js -t http -p 3000 \
-  --http-token your_secure_token_here \
-  --http-max-sessions 64 --http-session-idle-ms 1800000
-```
+HTTP sessions have **no idle-expiry timer**. They remain until explicit DELETE/SDK close, failed initialization, transport closure or listener shutdown; clients should explicitly close unused sessions. An abandoned session can retain a capacity slot until closed or shutdown. File/terminal leases, data-consumption deadlines and resource cleanup still apply independently and do not close the MCP session merely because it is idle. Unknown or closed session IDs return HTTP **404**; reconnect explicitly without the old ID, with no replay of tools, file commits or terminal input. This is not a global quota for background commands, nested MCP sessions or LSP servers.
 
 ### Session shutdown
 
 Normal SDK close, stdio EOF, and CLI SIGINT/SIGTERM/SIGHUP close session resources before process exit. Docker host-pipe EOF follows the same path. Cleanup fences new work immediately, closes skills watchers and debounce timers, and waits for file staging, accepted commits, data listeners and owned PTY exit. Repeated close waits the same cleanup; failures are reported rather than called successful. Synchronous exit cleanup remains a fallback until asynchronous cleanup finishes. SIGKILL/crashes and daemonized descendants are not guaranteed cleanups, and an unsettled underlying operation can delay graceful exit.
 
-A new HTTP session requires a POST initialize request without an MCP session ID. Unknown or closed IDs return HTTP 404; GET/DELETE/malformed requests do not create replacement sessions. Failed initialization releases its resources. Listener shutdown closes active and initializing sessions. Reverse reconnect creates a fresh server after the previous session cleanup completes; it never reuses closed watchers or replays operations. HTTP listener capacity and idle expiry follow the policy above; stdio and reverse are not idle-evicted.
+A new HTTP session requires a POST initialize request without an MCP session ID. Unknown or closed IDs return HTTP 404; GET/DELETE/malformed requests do not create replacement sessions. Failed initialization releases its resources. Listener shutdown closes active and initializing sessions. Reverse reconnect creates a fresh server after the previous session cleanup completes; it never reuses closed watchers or replays operations. HTTP listener capacity and lifetime follow the policy above; there is no listener idle eviction.
 
 ### Managed child MCP sessions
 
@@ -258,7 +258,7 @@ It will securely download, configure, and reload the skill without you lifting a
 | Option | Description | Default |
 | :--- | :--- | :--- |
 | `-w, --working-dir` | Staff workspace and default file root / terminal cwd; not an OS sandbox | `process.cwd()` |
-| `-d, --allowed-dir` | Extra directories for standard tools; does not add file-app roots | `[]` |
+| `-d, --allowed-dir` | Extra directories authorized for tools and, when enabled, file-app roots | `[]` |
 | `-r, --profile` | The active profile for skills (e.g., android-reverse) | `default` |
 | `--enable-lsp` | Enable LSP capabilities (disabled by default) | `false` |
 | `--docker` | Run inside a Docker container using this image | `undefined` |
@@ -271,8 +271,6 @@ It will securely download, configure, and reload the skill without you lifting a
 | `--rt, --reverse-token` | Security token for Reverse MCP | `undefined` |
 | `--rn, --reverse-name` | Server name for Reverse MCP | `undefined` |
 | `--extensions` | Comma-separated `files`, `terminal`, or both; apps/data dependencies are automatic | `[]` (all off) |
-| `--file-root` | Repeatable `id=path`; explicit file roots replace the default and apply only when files is enabled | `main=<working-dir>` |
-| `--shell` | Absolute executable PTY shell path | Valid absolute `$SHELL`, otherwise `/bin/bash` |
 | `--proxy` | HTTP(S) proxy for supported HTTP clients and reverse control/data HTTP requests | `undefined` |
 
 ### 🌐 Proxy Support (Corporate Networks)

package/README_zh.md

@@ -10,14 +10,16 @@
 
 ## 兼容性与配套升级
 
+**2.0.3 版本：** 交付 Linux PTY 预编译产物、明确报告终端启动失败，并避免 reverse 大回复阻塞心跳。配套将 chat-ai 升级至提交 `352bdb931bff38b5693dd386cd7584220571fd6b` 或其后继版本，以同时获得 App 窗口生命周期及关闭按钮修复。
+
 **破坏性升级：** reverse 连接与可选扩展需要配套 chat-ai 宿主：宿主须实现 reverse v1 与下文的会话相对数据路径合同。宿主、staff-mcp、描述符和 UI 资源须配套升级。
 
-标准 stdio/Streamable HTTP 的工具、资源和提示词继续保留。扩展**默认全关**；可选能力不可用或版本不匹配，不得拖垮健康的标准 MCP 连接。旧 reverse 握手本身不兼容，即使关闭所有扩展也不能解决，必须配套升级两端；不提供旧协议兼容模式，也不在断线后自动续传或重放输入。
+标准 stdio/Streamable HTTP 的工具、资源和提示词继续保留。扩展**默认全关**；可选发现或 data 协商失败仍保留健康的标准 MCP 连接。显式请求 terminal 但平台/native/shell 前提不可用时启动失败，不再静默禁用；files 原降级行为不变。旧 reverse 握手本身不兼容，即使关闭所有扩展也不能解决，必须配套升级两端；不提供旧协议兼容模式，也不在断线后自动续传或重放输入。
 
 无需进行 Chat8/schema9/format7/分享 protocol2 数据迁移。
 
 1. 结束在途操作，备份正常配置；无需转换数据。
-2. 先升级配套 chat-ai 宿主，再升级 staff-mcp 2.0.1，并协调 reverse 连接的停机窗口。
+2. 先升级配套 chat-ai 宿主，再升级 staff-mcp 2.0.3，并协调 reverse 连接的停机窗口。
 3. 重新连接 MCP、重新打开 App，仅显式启用需要的扩展。
 
 发布摘要见 [CHANGELOG](CHANGELOG.md)。
@@ -26,22 +28,22 @@
 
 需要 **Node.js 22.22.2 或更高版本**，Docker 镜像内也须满足。
 
-Linux 与 Linux 宿主＋本地 Docker Engine 是主要完整扩展环境，仍须满足下述前提。Windows 原生标准 MCP（stdio、HTTP）与 Windows Docker 标准 MCP 已验证，不代表完整扩展支持。非 Linux Docker launcher 禁用可选扩展。**macOS 未实测**，路径转换能力不等于平台支持承诺。
+Linux 与 Linux 宿主＋本地 Docker Engine 是主要完整扩展环境，仍须满足下述前提。Windows 原生标准 MCP（stdio、HTTP）与 Windows Docker 标准 MCP 已验证，不代表完整扩展支持。非 Linux Docker launcher 对显式 terminal 请求报错；仅 files 仍警告并禁用。**macOS 未实测**，路径转换能力不等于平台支持承诺。
 
-可指定版本运行 staff-mcp 2.0.1：
+可指定版本运行 staff-mcp 2.0.3：
 
 ```bash
-npx --yes staff-mcp@2.0.1 --working-dir /path/to/your/project
+npx --yes staff-mcp@2.0.3 --working-dir /path/to/your/project
 ```
 
-从 staff-mcp 2.0.1 源码 checkout 使用时，先安装依赖并构建，再使用以下示例中的绝对入口：
+从源码 checkout 使用时，先安装依赖并构建，再使用以下示例中的绝对入口：
 
 ```bash
 npm ci
 npm run build
 ```
 
-将 `/path/to/staff-mcp` 替换为实际构建目录。Docker 只读挂载仍要求兼容的 Node/native ABI/libc；宿主构建的 optional PTY 不保证能在任意镜像内使用。
+将 `/path/to/staff-mcp` 替换为实际构建目录。Docker 仍只读挂载宿主程序包及 `node_modules`，并非容器依赖完全隔离。2.0.3 将 optional `node-pty` 精确锁定为官方预发布版 `1.2.0-beta.18`，内含 Linux x64/arm64、glibc >= 2.28 的 N-API 预编译；运行时仍需要系统 `libstdc++`、`libgcc` 等库。本次解决正常安装的预编译交付，不消除本地构建残留或架构/libc/平台不匹配限制，N-API 也不消除这些限制。不自动升级用户镜像，不承诺 musl/Alpine 的 terminal 支持。
 
 ### 1. 标准宿主机模式
 直接在物理机或虚拟环境中运行。
@@ -50,10 +52,10 @@ node /path/to/staff-mcp/dist/src/index.js --working-dir /path/to/your/project
 ```
 
 ### 2. Docker 透明代理模式 (Cyber-Shell)
-在兼容的 Docker 镜像中运行 staff-mcp，保留宿主的标准 MCP 控制连接。wrapper 自动挂载项目和程序包；启动仍取决于镜像、Node/native ABI/libc 和挂载权限。Linux 宿主＋本地 Docker Engine 是完整扩展支持路径。非 Linux Docker launcher 对请求的 Apps/files/terminal 扩展警告后禁用；Windows Docker 已验证基础 MCP，macOS 未实测；基础 Docker 连接仍要求 daemon 可达及 bind mount 路径有效。
+在兼容的 Docker 镜像中运行 staff-mcp，保留宿主的标准 MCP 控制连接。wrapper 自动挂载项目和程序包；启动仍取决于镜像、Node/native ABI/libc 和挂载权限。Linux 宿主＋本地 Docker Engine 是完整扩展支持路径。非 Linux Docker launcher 对显式 terminal 请求启动报错，仅 files 仍警告并禁用；Windows Docker 已验证基础 MCP，macOS 未实测；基础 Docker 连接仍要求 daemon 可达及 bind mount 路径有效。
 
 ```bash
-# 在一个纯净的 Alpine Node 容器里调试你的代码
+# 仅普通 MCP，不启用 terminal：在 Alpine Node 容器内调试代码
 node /path/to/staff-mcp/dist/src/index.js --docker node:22-alpine
 
 # 在自带逆向工程工具链的镜像里执行安全分析
@@ -79,7 +81,7 @@ node /path/to/staff-mcp/dist/src/index.js --docker chineseastar/security:latest
 ```
 
 ### 4. Reverse MCP 模式 (内网穿透)
-staff 从 NAT/防火墙后主动连接 chat-ai 现有 Web 入口，无需本地入站 listener。控制使用 SSE + POST，文件/终端通过 remote 主动 raw HTTP GET/PUT 走同一 Web 端口。chat-ai 提供当前会话的数据路径，staff 用已有 `--ru` 的 origin 解析；chat-ai 的 `MCP_REVERSE_URL` 只作为可选连接指引，不是数据通道前提。断线使用新 session，不重放工具调用、文件句柄或终端输入。
+staff 从 NAT/防火墙后主动连接 chat-ai 现有 Web 入口，无需本地入站 listener。控制使用 SSE + POST，文件/终端通过 remote 主动 raw HTTP GET/PUT 走同一 Web 端口。chat-ai 提供当前会话的数据路径，staff 用已有 `--ru` 的 origin 解析；chat-ai 无需配置公网地址环境变量。断线使用新 session，不重放工具调用、文件句柄或终端输入。
 
 ```bash
 node /path/to/staff-mcp/dist/src/index.js -t reverse \
@@ -123,6 +125,8 @@ token。这里使用服务端共享 token，不提供 OAuth 流程。
 
 Reverse GET `<base>/sse`，携带 `Authorization: Bearer <token>` 与 `X-MCP-Server-Name`；SSE endpoint 事件给出 POST 回送地址，message 事件直接承载 MCP JSON-RPC，无私有信封。源码接受显式 HTTP/HTTPS；HTTP 每次启动警告一次明文风险，不能保护 token 或正文，不可信网络应使用 HTTPS。HTTPS 验证证书与目标身份，不自动降级；配置基址无凭据、query、fragment。无需 WebSocket upgrade、独立 gateway/launcher 或私有 host leg。SDK 初始化、数据面就绪和用户授权是不同事实；短暂连接不重置指数退避。
 
+仅已识别的入站标准 MCP `ping` 的响应使用独立有界 POST 发送 lane；其他 POST 仍 FIFO，不重放请求/输入、不改变协议版本或新增 flag，也不延长 timeout。慢发送诊断区分排队等待与 POST elapsed，仅记录 metadata，不记录 token、URL 或 body；host 另记录 App resource-read 时间与字节数元数据。
+
 可配置参数（毫秒，Docker 也透传）：
 
 - `--reverse-connect-timeout`：15000，0 仅禁用 SSE 建连超时。
@@ -136,21 +140,25 @@ Reverse GET `<base>/sse`，携带 `Authorization: Bearer <token>` 与 `X-MCP-Ser
 
 ## 🛠️ 核心能力
 
+以下运行时行为适用于 staff-mcp 2.0.3；扩展仍须显式启用。
+
 扩展**默认全关**。通过 `--extensions files`、`--extensions terminal` 或 `--extensions files,terminal` 启用；apps/data 依赖及 terminal 对 streams v1 的声明自动计算，无需单独选择。禁用能力不声明对应 manifest 条目、不注册对应 UI Resource 或业务 handler；全关时无扩展 manifest、应用数据 listener/session，普通 MCP 工具和非 UI Resources 保留。HTTP 模式仍监听原 MCP 服务。
 
 ```bash
 # 仅文件应用，默认 main 根为 --working-dir
 node /path/to/staff-mcp/dist/src/index.js --extensions files -w /workspace
 # 仅终端，不隐式启用文件应用
-node /path/to/staff-mcp/dist/src/index.js --extensions terminal --shell /bin/bash
-# 两种应用，显式文件 roots 替代默认 main 根
+node /path/to/staff-mcp/dist/src/index.js --extensions terminal
+# 两种应用；显式授权 assets，工具与文件应用共用
 node /path/to/staff-mcp/dist/src/index.js --extensions files,terminal -w /workspace \
-  --file-root main=/workspace --file-root assets=/srv/assets
-# 在适用 Linux 宿主上明确开放全盘文件访问（不是默认值）
-node /path/to/staff-mcp/dist/src/index.js --extensions files --file-root system=/
+  -d /srv/assets
+# 在适用 Linux 宿主上明确向工具和文件应用授权全盘（不是默认值）
+node /path/to/staff-mcp/dist/src/index.js --extensions files -d /
 ```
 
-`--file-root id=path` 可重复，id 须由小写字母/数字/连字符组成且唯一；相对路径按启动进程 cwd 解析。显式 roots **替代**而非追加默认 `main`，仅 files 启用时影响文件 App 及其标准文件 Resources，不改变标准工具的 `--working-dir` / `--allowed-dir` 范围或终端默认工作区 cwd。显式选择 `/` 开放的是 staff 身份实际可见的文件系统，不提权，也不是 OS 安全边界。库接口 [`ExtensionOptions`](src/extensions/config.ts) 为 `{enabled?:('files'|'terminal')[],fileRoots?:{rootId:string,directory:string}[],shell?:string}`，`enabled` 默认 `[]`。
+files 启用时直接复用标准工具目录授权：`main` 是 `--working-dir`，其后按解析、去重后的 `--allowed-dir` 顺序生成 `extra1`、`extra2` 等根。显式 `-d` 授权因此也在文件 UI 可见，不自动添加系统根。相对目录按启动进程 cwd 解析。`-d /` 是向工具及文件应用显式授权 staff 身份可见的文件系统，仍受 OS 权限约束，不提权，也不是 shell 沙箱。库接口 [`ExtensionOptions`](src/extensions/config.ts) 为 `{enabled?:('files'|'terminal')[]}`，默认 `[]`。
+
+`--file-root`、`--shell`、`--http-max-sessions`、`--http-session-idle-ms` 已删除，传入时明确报 unknown option。请从启动配置移除，文件目录改用 `-w` / `-d`，shell 使用正常的 `SHELL` 环境变量；不提供兼容回退。
 
 ### 独立文件工作区
 
@@ -160,7 +168,7 @@ node /path/to/staff-mcp/dist/src/index.js --extensions files --file-root system=
 
 ### 人工终端（显式启用扩展）
 
-`--extensions terminal` 须 Linux、可加载的 optional `node-pty`、可执行 shell 及协商 streams/data v1 后可用的 duplex dataSession，可经本机 stdio/本地 Docker、direct HTTP 或 reverse 接入。Linux/native PTY/shell 不可用时通过 stderr 明确警告，只禁用 terminal/streams，不让整个 MCP 启动失败；标准工具与可用的 files 扩展保留。默认关闭时不加载原生 PTY。`--shell` 接受绝对可执行路径，缺省使用有效的绝对 `$SHELL`，否则回退 `/bin/bash`。交互 shell 读取正常启动配置，继承 staff 环境，仅排除[终端合同](docs/terminal.md)列出的精确内部控制 key。chat-ai 沿用当前会话 MCP 授权及同源浏览器请求，不另设终端权限开关或高危确认。终端遵循宿主站点统一的 HTTP/HTTPS 部署策略，不另设终端专用 TLS 门槛或 origin 白名单。建议全站使用 HTTPS 保护登录会话、工具调用及终端流量；允许 HTTP 不代表这些请求已加密。
+`--extensions terminal` 须 Linux、可加载的 optional `node-pty`、可执行 shell 及协商 streams/data v1 后可用的 duplex dataSession，可经本机 stdio/本地 Docker、direct HTTP 或 reverse 接入。显式请求 terminal 但 Linux/native PTY/shell 不可用时明确报错并启动失败，即使同时请求 files 也不静默移除 terminal。默认关闭时不加载原生 PTY。自动使用有效的绝对可执行 `$SHELL`，否则使用 `/bin/bash`；若仍不可用，显式 terminal 请求启动失败，不再尝试其他 shell。交互 shell 读取正常启动配置，继承 staff 环境（包括正常的 `HOME`），仅排除[终端合同](docs/terminal.md)列出的精确内部控制 key。chat-ai 沿用当前会话 MCP 授权及同源浏览器请求，不另设终端权限开关或高危确认。终端遵循宿主站点统一的 HTTP/HTTPS 部署策略，不另设终端专用 TLS 门槛或 origin 白名单。建议全站使用 HTTPS 保护登录会话、工具调用及终端流量；允许 HTTP 不代表这些请求已加密。
 
 PTY 默认从 staff 工作区 `main` 启动，与文件 roots 独立，以 staff 的 OS uid 运行；root/cwd 只是起始目录，**不是 sandbox**；shell 的文件和网络副作用不受文件工具路径检查约束。终端输入输出不进入模型或聊天历史。每个 stream 的浏览器到 chat-ai 交互使用一条同源 WebSocket（`/api/mcp/app-stream`，`chat-app-stream-v1`），输入、输出、resize、presence 和真实 xterm 消费 ACK 共用连接，后端仍是公共 HTTP dataSession。浏览器每 10 秒刷新独立的 120 秒 host presence；host 通用 streams 模块按远端每次返回的租约调度续租，staff 默认 30 秒。点击 Shell App 自动启动一次 PTY，无额外打开按钮或确认；退出、PTY 错误或真实断链后保留 App 壳供手动重连。普通隐藏视图保留 read/ACK/presence，但拒绝新输入和 resize；真正离页、关闭、撤权或到期才清理，后代回收 best effort，不撤销副作用。
 
@@ -174,17 +182,19 @@ PTY 默认从 staff 工作区 `main` 启动，与文件 roots 独立，以 staff
 - 自动处理 Windows/Mac 与 Linux 容器之间的路径转换问题。
 - 容器名自带启动上下文（例如 `staff-mcp-myproj-3000-a1b2c3` = 工作区 `myproj`、HTTP 端口 `3000`、随机后缀 `a1b2c3`），多个会话并存时在 `docker ps` 中一眼可辨。
 - 将独立的 Docker 工具缓存 `<staff-global>/tools/docker` 挂到 `/opt/.staff/tools`，并保留原 skills/profiles 挂载。同 uid 非 root 可直接写工具目录，不覆盖宿主原工具缓存；仍受原有挂载权限限制，不自动 chown/chmod。
-- 提供 `--docker-args` 配置兼容的硬件/环境参数（如 ADB USB 调试、GPU）；stdio 数据拓扑不匹配只禁用可选扩展，覆盖内部 bootstrap/映射及容器生命周期管理参数仍然报错。
+- 提供 `--docker-args` 配置兼容的硬件/环境参数（如 ADB USB 调试、GPU）；stdio 数据拓扑不匹配对显式 terminal 请求报错，仅 files 保持原降级行为；覆盖内部 bootstrap/映射及容器生命周期管理参数仍然报错。
 
 **受支持的 Linux 本地 Docker stdio 仅在至少实际启用一种扩展时**，由原 wrapper 自动预留容器私有端口到 **127.0.0.1 随机宿主端口**，仅 inspect 自己 cidfile 的容器；只读挂载宿主 **0600 metadata 文件**提供可达 baseUrl，不改 stdin/stdout，不手找容器 IP，应用 listener 等 `data/v1/configure` 才懒启动。全关时 `dataAuto` 为 false，不分配应用数据发布端口、metadata 挂载或 bootstrap；普通工作区/程序包挂载不变。非 Docker stdio 也在 configure 前无应用 listener。HTTP/reverse 不增加这项发布；全关无 dataSession，HTTP 原 MCP listener 保留。
 
-files 启用时，每个显式 Docker `--file-root id=path` 将对应宿主目录 bind-mount 到 `/opt/staff-file-roots/<id>`。因此 `--file-root system=/` 是明确把宿主根挂到该目录，而不只是指容器根；这是主动扩大文件可见范围，不是自动获得宿主权限或全平台支持承诺，仍受实际 OS/容器权限与 Docker 拓扑约束。默认文件 `main` 与终端 cwd 沿用现有工作区挂载。
+Docker 文件根仅复用已有工作区（`/workspace`，`main`）与 allowed-directory 挂载，不创建第二套 file-root 挂载。显式 `-d /` 会通过已有授权目录映射主动扩大宿主文件访问范围，仍受 Docker/OS 权限与拓扑约束。终端 cwd 始终为 `/workspace`，不受额外文件根影响。
+
+Docker 中普通工具与文件应用复用允许目录挂载。宿主文件系统根（如 `/`）会映射到 `/opt/staff-allowed/root-N`，因为 Docker 禁止挂载到容器 `/`；容器内 `-d` 和受保护暂存别名同时使用映射路径。
 
-此应用数据路径要求本地 daemon、宿主客户端与 wrapper 共享可达 loopback、兼容 bridge/端口发布。非 Linux Docker launcher，以及 stdio 的 remote/TCP/SSH daemon 或 host/container 网络等不匹配情况，会明确警告并禁用可选扩展；只要 Docker 自身能正常启动，基础 MCP 连接和工具仍保留。HTTP/reverse 不需要这项 stdio 映射。数据 bootstrap 或 configure 失败不得终止健康的 MCP 控制连接，依赖数据通道的 App 不开放，不回退旧字节协议、不重放操作。loopback 发布不是敌对容器隔离保证；metadata 保持 0600，容器 uid 须能读取，工作区/全局目录权限与 PTY ABI/libc 仍须匹配。不自动 chown、放宽权限或切换浏览器用户身份。正常退出及信号仍清理自有容器、映射和 metadata，不提供跨重启资源恢复。
+此应用数据路径要求本地 daemon、宿主客户端与 wrapper 共享可达 loopback、兼容 bridge/端口发布。非 Linux Docker launcher，以及 stdio 的 remote/TCP/SSH daemon 或 host/container 网络等不匹配情况，对显式 terminal 请求明确启动报错；未请求 terminal 时，files 仍警告并禁用，只要 Docker 自身能正常启动，基础 MCP 连接和工具仍保留。HTTP/reverse 不需要这项 stdio 映射。数据 bootstrap 或 configure 失败不得终止健康的 MCP 控制连接，依赖数据通道的 App 不开放，不回退旧字节协议、不重放操作。loopback 发布不是敌对容器隔离保证；metadata 保持 0600，容器 uid 须能读取，工作区/全局目录权限与 PTY ABI/libc 仍须匹配。不自动 chown、放宽权限或切换浏览器用户身份。正常退出及信号仍清理自有容器、映射和 metadata，不提供跨重启资源恢复。
 
-### 扩展可用性不决定 MCP 是否可连接
+### 可选协商降级与显式 terminal 启动错误
 
-files、terminal 和当前连接的数据通道分别判断可用性。缺少终端运行时只禁用 terminal；可选文件根不可用只禁用 files，标准工作区工具/资源保留。未知或不匹配的扩展版本不开放对应 handlers/App。chat-ai 在标准 initialize 成功后，即使 Apps 发现或 data configure 失败，仍保留正常的 tools/resources/prompts。降级原因写 stderr，不混入 stdio 的 JSON-RPC stdout。
+files、terminal 和当前连接的数据通道分别判断可用性。缺少终端运行时在显式请求 terminal 时导致启动失败；默认关闭时不加载原生 PTY。可选文件根不可用仍只禁用 files，标准工作区工具/资源保留。未知或不匹配的扩展版本不开放对应 handlers/App。chat-ai 在标准 initialize 成功后，即使 Apps 发现或 data configure 失败，仍保留正常的 tools/resources/prompts。降级原因写 stderr，不混入 stdio 的 JSON-RPC stdout。
 
 这不是绕过鉴权或生命周期：CLI 参数语法错误、Docker 自身启动失败、凭据错误和标准 MCP 控制连接/初始化失败仍须报错。工作区/全局挂载的权限错误仍在相关启动或文件/工具操作中返回错误；扩展降级不授予额外访问，也不表示启动时已预检所有目录。新旧 reverse 控制协议不兼容仍需两端配套升级，不能用可选能力降级掩盖；文件提交、工具副作用和终端输入也不会自动重试。
 
@@ -210,27 +220,17 @@ node /path/to/staff-mcp/dist/src/index.js --profile android-reverse
 ```
 
 
-### HTTP 会话容量与空闲回收
-
-每个 HTTP 监听器默认最多 **64 个会话**。初始化中、清理未完成或清理失败的会话都计入名额。满额时新初始化返回 **429**，不驱逐已有会话；清理成功后才释放名额。使用 `--http-max-sessions <正整数>` 配置。它与限制受管子 MCP 的 `--max-mcp-sessions` 独立。
+### HTTP 会话容量与生命周期
 
-HTTP 会话在观察到空闲 **30 分钟**后可被回收（`--http-session-idle-ms <毫秒>`，1..2147483647）。每个监听器仅一个扫描定时器，间隔最多一分钟，配置更短时使用该短间隔。有效的入站 MCP 控制消息重新开始空闲宽限期；单纯 GET/SSE 长连接、服务端通知、无效 HTTP 请求和未认证的数据请求不保活。
+每个 HTTP 监听器固定最多 **64 个会话**，为内部常量。初始化中、清理未完成或清理失败的会话都计入名额。满额时新初始化返回 **429**，不驱逐已有会话；清理成功后才释放名额。它与限制受管子 MCP 的 `--max-mcp-sessions` 独立，子 MCP 显式 start/stop 不变。
 
-未完成的请求 handler（即使 HTTP 断开或收到取消）、文件准备/有效租约/在途写入或提交、数据配置/通道，以及自有 PTY、输出排空或退出等待都会阻止空闲回收。判断从各资源已有状态派生，不续业务租约，不把取消视为执行已完成。活动结束后，下一次观察到空闲时重新给予完整宽限期。已结束的结果记录和没有通道的已配置数据会话本身不保活。
-
-过期会话 ID 返回 **404**，即使请求体是 initialize 也一样。需不带旧 ID 显式重连，不重放工具、文件提交或终端输入。仅保留 App iframe 或未保存浏览器草稿不会保活服务端连接；草稿仍归客户端，但过期后服务端操作需要新连接/App。该策略仅作用于 HTTP 监听器会话，不回收 stdio/reverse；Docker HTTP 会转发两个参数。它不等于进程级后台命令、受管子 MCP 或 LSP 的全局配额，真正未完成的工作或清理失败仍可能持续占用名额。
-
-```bash
-node /path/to/staff-mcp/dist/src/index.js -t http -p 3000 \
-  --http-token your_secure_token_here \
-  --http-max-sessions 64 --http-session-idle-ms 1800000
-```
+HTTP 会话**不按空闲超时回收**。显式 DELETE/SDK close、初始化失败、传输关闭或监听器 shutdown 才清理会话；客户端应主动关闭不再使用的连接。遗留会话可能持续占用名额，直到关闭或 shutdown。文件/终端租约、数据消费期限及资源清理仍独立生效，不因 MCP 空闲而主动关闭整个会话。未知或已关闭 ID 返回 **404**，需不带旧 ID 显式重连，不重放工具、文件提交或终端输入。此容量不是后台命令、受管子 MCP 或 LSP 的全局配额。
 
 ### 会话关闭
 
 正常 SDK close、stdio EOF 及 CLI SIGINT/SIGTERM/SIGHUP 都先清理会话资源，再退出进程；Docker 宿主管道 EOF 走同一路径。清理立即拒绝新操作，关闭 skills 监听器及防抖定时器，并等待文件暂存、已受理提交、数据监听器和自有 PTY 退出。重复 close 等待同一清理过程，失败明确报告，不伪报成功。异步清理结束前保留同步 exit 兜底。SIGKILL、崩溃和 daemonize 后代不保证清理，未兑现的底层操作也可能延迟正常退出。
 
-新 HTTP 会话只能由不带 MCP session ID 的 POST initialize 创建。未知或已关闭 ID 返回 404；GET/DELETE/无效请求不会创建替代会话。初始化失败会释放资源，监听器停止时等待活动及初始化中的会话。reverse 重连等待旧会话清理后创建新 server，不复用已关闭的监听器、不重放操作。HTTP 监听器容量与空闲回收遵循上节规则，stdio/reverse 不按空闲回收。
+新 HTTP 会话只能由不带 MCP session ID 的 POST initialize 创建。未知或已关闭 ID 返回 404；GET/DELETE/无效请求不会创建替代会话。初始化失败会释放资源，监听器停止时等待活动及初始化中的会话。reverse 重连等待旧会话清理后创建新 server，不复用已关闭的监听器、不重放操作。HTTP 监听器容量与生命周期遵循上节规则，不再按空闲回收。
 
 ### 受管子 MCP 会话
 
@@ -254,7 +254,7 @@ node /path/to/staff-mcp/dist/src/index.js -t http -p 3000 \
 | 选项 | 描述 | 默认值 |
 | :--- | :--- | :--- |
 | `-w, --working-dir` | staff 工作区与默认文件 root / 终端 cwd；不是 OS 沙盒 | `process.cwd()` |
-| `-d, --allowed-dir` | 标准工具额外允许目录；不增加文件 App roots | `[]` |
+| `-d, --allowed-dir` | 工具及已启用文件 App 共用的额外授权目录 | `[]` |
 | `-r, --profile` | 当前激活的技能档案/工种 (如 android-reverse) | `default` |
 | `--enable-lsp` | 启用 LSP 语言服务器功能 (默认禁用) | `false` |
 | `--docker` | 在指定的 Docker 镜像内运行 AI | `undefined` |
@@ -267,8 +267,6 @@ node /path/to/staff-mcp/dist/src/index.js -t http -p 3000 \
 | `--rt, --reverse-token` | Reverse MCP 的安全认证令牌 | `undefined` |
 | `--rn, --reverse-name` | Reverse MCP 的服务注册名称 | `undefined` |
 | `--extensions` | 逗号分隔的 `files`、`terminal` 或两者；自动计算 apps/data 依赖 | `[]`（全关） |
-| `--file-root` | 可重复 `id=path`；显式 roots 替代默认值，仅 files 启用时生效 | `main=<working-dir>` |
-| `--shell` | PTY shell 的绝对可执行路径 | 有效的绝对 `$SHELL`，否则 `/bin/bash` |
 | `--proxy` | 支持的 HTTP 客户端及 reverse 控制/数据 HTTP 请求 的 HTTP(S) 代理 | `undefined` |
 
 ### 🌐 代理支持（企业内网）

package/dist/src/data/HttpDataSession.d.ts

@@ -10,7 +10,6 @@ export declare class HttpDataSession {
     private readonly endpoint?;
     private readonly maximum;
     constructor(options: HttpDataSessionOptions);
-    hasActivity(): boolean;
     supports(purpose: ChannelPurpose, direction: Direction): boolean;
     private admit;
     private validateLink;

package/dist/src/data/HttpDataSession.js

@@ -636,9 +636,6 @@ export class HttpDataSession {
         if (options.endpoint)
             this.endpoint = endpointUrl(options.endpoint);
     }
-    hasActivity() {
-        return this.pendingOpens.size > 0 || this.channels.size > 0;
-    }
     supports(purpose, direction) {
         return (!this.stopped &&
             validPurpose(purpose) &&