wsctl 0.1.2__tar.gz → 0.1.4__tar.gz

wsctl-0.1.4/.dockerignore

@@ -0,0 +1,19 @@
+# 构建上下文是仓库根目录（见 contrib/docker/Dockerfile 的说明），
+# 这里排除与镜像无关的大目录，加快构建并避免把本地垃圾拷进去。
+.git
+.github
+.venv
+venv
+__pycache__
+*.pyc
+*.pyo
+.mypy_cache
+.pytest_cache
+.ruff_cache
+dist
+build
+*.egg-info
+docs/screenshots
+data
+*.tar.gz
+*.log

{wsctl-0.1.2 → wsctl-0.1.4}/CHANGELOG.md

@@ -5,6 +5,258 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.4] - 2026-09-22
+
+Reliability and usability release. Every promise the product makes now holds
+across a restart, a broken disk and a broken config edit; the CLI can log in
+with 2FA and script against JSON. No new terminal protocols.
+
+### Added
+
+- **CLI can log in to a two-factor account.** `wsctl login --totp 123456`, the
+  `WSCTL_TOTP` environment variable, or a prompt when the server asks for a
+  code. Previously a 2FA-enabled account made every CLI command unusable.
+- **Share links survive a server restart.** The token, its expiry and its
+  writable flag are persisted with the session (`term_sessions.share_*`,
+  schema version 4) and rehydrated verbatim on adoption, so a QR code that was
+  already handed out keeps working — the same promise the session itself makes
+  on the tmux backend. Renaming a session no longer invalidates its link.
+- **Minimum password policy** (non-empty, at least 8 characters), enforced in
+  one place (`core/passwords.validate_password`) at the storage boundary, in
+  `user_admin`, and therefore by both the HTTP API and the CLI. Existing
+  passwords are *not* force-changed; `wsctl doctor` warns instead of locking
+  anyone out.
+- **Log rotation** for the background lifecycle. `log_file` / `log_max_bytes` /
+  `log_backup_count` rotate by copy-and-truncate, so the append-mode descriptor
+  `wsctl start` hands its child stays valid across a rotation (rename-based
+  rotation would leave the daemon writing into the rotated file forever).
+- **Web new-session dialog** with name, command, working directory, backend and
+  a structured SSH target form (host / user / port / identity / `ssh -o`
+  options). `Alt+N` still opens a default shell with one keystroke.
+- **Web admin "config" tab**: the effective configuration, each key labelled
+  `热更新` or `需重启`, plus a reload button that reports exactly what changed
+  *and* what failed to parse.
+- **`wsctl completion install|show [bash|zsh|fish|powershell]`**. Typer's
+  `--install-completion` only ever installs bash; this covers the rest and
+  picks the shell from `$SHELL` instead of guessing bash.
+- `GET /api/config` (admin) — the read-only effective-configuration view behind
+  the new tab.
+- CLI `--json` on `session list|new|rename`, `user add|list`, `audit` and
+  `config show|get`; `wsctl audit` gained `--event` / `--user-id` / `--ip` filters;
+  `wsctl session list` now shows the owner's **username** (and the backend and
+  liveness) instead of a bare numeric id.
+- `wsctl logs` reads across rotated backups, so a rotation never hides history.
+- `wsctl doctor` additionally reports free disk space on the data partition,
+  the password policy in force, the log file and its rotation threshold, and
+  the system clock (which TOTP depends on).
+- Metrics `wsctl_pty_input_dropped_total` and `wsctl_recording_failures_total`.
+- Uploads can opt in to replacing an existing file (`overwrite=1`); the web UI
+  asks first.
+- File listings report `truncated` and `limit` when a directory exceeds 2000
+  entries instead of silently returning everything.
+
+### Changed
+
+- **A broken config edit is no longer silent.** `reload_settings_file` returns
+  `(changed, errors)`; `wsctl reload` and `POST /api/config/reload` surface the
+  exact TOML/validation error and exit non-zero, and the server logs it.
+  Previously an invalid value was discarded and the reload reported "no
+  changes", which was indistinguishable from the reload not running.
+- **`config set` preserves trailing comments** on the line it edits
+  (`port = 7681  # 监听端口` stays annotated) and no longer mistakes a
+  commented-out `# port = 1234` for the real key.
+- **Web terminal connections are bounded.** At most `8` sessions hold a live
+  socket (the most recently used ones); the rest appear in the tab bar as
+  `未连接` and attach when opened. Previously every session opened a WebSocket
+  and an xterm instance at page load, which fell over past a handful.
+- Uploading over an existing file is refused with `409` unless the client
+  explicitly opts in. Files were previously truncated without warning.
+- The image in `contrib/docker` builds from the **repository root** and installs
+  the local source; `docker compose` refuses to start without
+  `WSCTL_ADMIN_PASSWORD` instead of defaulting to `change-me`.
+- CI adds a macOS leg and a Windows import/CLI smoke job, runs the `-m slow`
+  load suite, installs `lrzsz` so the ZMODEM round trip is really exercised,
+  and builds the Docker image.
+
+### Fixed
+
+- **A session whose child never exits can no longer hang the server.**
+  `TermSession._finalize` waited unboundedly on `Pty.wait()`; a daemonized
+  grandchild holding the terminal open would wedge the read loop's cleanup
+  forever and leak the session object. The wait is now bounded and escalates to
+  `kill`.
+- **A failed recording no longer claims to be recording.** When the writer hit a
+  disk error it silently stopped while `is_recording` stayed true, so the UI
+  showed a red dot for a file that was not being written. The recorder now
+  closes itself, records the error, and `close()` can no longer race the writer
+  thread into a half-closed file.
+- **`import wsctl.core.store` no longer computes an Argon2 hash**, which made
+  every CLI invocation — including `wsctl --version` — pay ~120ms before doing
+  anything. The timing-equalising dummy hash is computed lazily; combined with
+  lazy imports of the server/client dependencies, `wsctl version` went from
+  ~1.05s to ~0.36s.
+- **Authentication lookups no longer run on the event loop.** The WebSocket
+  handshake and its periodic re-check did synchronous SQLite work per
+  connection every 5s, as did the maintenance loop's leases/reaping/retention.
+  They now run on worker threads, and a short-lived auth cache
+  (`core/authcache.py`) turns the re-check into a dict lookup. Revocation stays
+  immediate: disabling a user, changing a password or changing a role drops that
+  user's cache entries at once.
+- **A dropped keystroke is now reported.** When a session's child stops
+  draining its terminal the write path drops input rather than grow without
+  bound — but it did so *silently*, which looked like a dead keyboard. The
+  client is told once (`终端输入过快，部分按键已丢弃`) and the drops are counted.
+- **A stale `attached` message can no longer revert a rename.** The tab label
+  is protected by a rename generation counter, so a reconnect that echoes the
+  pre-rename name does not silently undo what the user just typed.
+- **`promptDialog`/`confirmDialog` are singletons.** A second invocation while
+  one was open overwrote the input the user was typing into; that is how a
+  rename could send the *old* name back to the server and look lost.
+- **A finished ZMODEM transfer always releases the keyboard.** The input lock
+  was only cleared by the transfer's end event, so an aborted transfer left the
+  terminal accepting no input at all. An inactivity watchdog now force-releases
+  it (and `on_retract` does too).
+- `wsctl connect` survives non-JSON text frames (a proxy or middlebox injecting
+  one used to tear the connection down with a traceback).
+- **Maintenance reconciliation can no longer mis-kill a live session.**
+  `term_session_stop_missing` takes the in-memory session set as its liveness
+  list; running its `UPDATE` on a worker thread after taking that snapshot
+  widened the window to thread-scheduling latency, so a session created in
+  between would be written as `stopped` while running (and never adopted again
+  after a restart). The snapshot and that one statement stay in a single
+  synchronous stretch on the loop; only snapshot-independent writes are
+  threaded.
+- **Argon2 hashing no longer runs under the store lock.** `user_create` and
+  `user_set_password` hashed while holding the single store mutex, serialising
+  every other database operation — including authentication — behind one
+  ~100ms CPU-bound hash. The hash is now computed before the lock is taken.
+- **Audit input records only what actually reached the shell.** Keystrokes
+  dropped by write backpressure (or a session that had already exited) used to
+  be audited as if the command had run. Dropped input is now reported to the
+  user and simply not recorded.
+- The terminal connection indicator follows the *visible* tab: a background
+  tab reconnecting or being suspended no longer rewrites it to
+  "连接中"/"空闲".
+- Metrics named `_total` (`wsctl_audit_dropped_total`,
+  `wsctl_audit_write_errors_total`, `wsctl_pty_input_dropped_total`,
+  `wsctl_recording_failures_total`) are now exposed with `# TYPE … counter`.
+  They were declared `gauge`, which makes `rate()` reject them. The two new
+  ones are also genuinely monotonic — a per-session sum would have gone *down*
+  whenever a session ended, showing up as counter resets.
+- Metric label values are escaped for the Prometheus text format (a `"` or
+  newline in a label produced invalid exposition output).
+- Scrollback eviction no longer leaves an orphaned UTF-8 continuation byte at
+  the head of a replayed screen (rendered as a replacement glyph).
+- `wsctl doctor` no longer imports the hashing stack just to print a table.
+
+### Testing
+
+- New suites for the password policy, the auth cache (including revocation
+  guarantees), copy-and-truncate log rotation, recording-failure honesty,
+  scrollback UTF-8 alignment and metric label escaping; extended suites for
+  share persistence (including "a rename must not invalidate the link"),
+  the bounded `Pty.wait`, PTY input drops, the upload overwrite guard, the
+  config endpoint and reload errors, TOTP/`--json`/comment-preserving
+  `config set`, and `completion show`.
+- The browser suite covers the new-session dialog (including the SSH-required
+  validation), the config tab, the upload overwrite prompt, the bounded
+  connection budget, and a **real ZMODEM `sz`/`rz` byte-exact round trip**.
+- `scripts/e2e/run_all.py` asserts that a share link keeps working across a
+  full server restart, and reports the child's log when a scenario fails to
+  start.
+
+### Upgrade notes
+
+- The database migrates to schema version 4 (adds `share_token`,
+  `share_expires`, `share_writable` to `term_sessions`). The migration is
+  idempotent, but **back up before downgrading** to 0.1.3 or older —
+  `wsctl backup` first, since the older release does not know about these
+  columns.
+- New accounts and password changes must be at least 8 characters. Existing
+  accounts keep working; `wsctl doctor` reports which ones are below the bar.
+
+[0.1.4]: https://github.com/ThzxxArt/wsctl/releases/tag/v0.1.4
+
+## [0.1.3] - 2026-09-22
+
+Operations and correctness release: a background lifecycle that needs no
+systemd, strict validation of mutually exclusive options, and the last blocking
+paths on the event loop removed. No new terminal protocols.
+
+### Added
+
+- **Background lifecycle without systemd**: `wsctl start` / `stop` / `restart` /
+  `status` / `logs` / `reload`, plus `wsctl serve --daemon`. The child is
+  detached (`start_new_session`), its output goes to a per-port log file, and a
+  pid file carries a **process-identity fingerprint** (Linux start time, `ps`
+  elsewhere) so a recycled PID is never signalled. `start` refuses to clobber a
+  live instance (`start --force` replaces a running one); `status --json` is
+  machine-readable; `reload` sends `SIGHUP`, which the server now handles (in
+  addition to the mtime watcher).
+- **Half-open connection detection**: a WebSocket that has sent nothing for
+  `IDLE_TIMEOUT` (120s) is closed with code `4408`. Both clients ping every 25s,
+  so a peer that vanished without a FIN is reclaimed instead of lingering.
+- **Declarative CLI validation** (`wsctl/cli/validate.py`): options that cannot
+  be combined or that depend on each other now fail fast with exit code 2 and an
+  actionable message — `--daemon` vs `--reuse-port`, `--ssl-cert`/`--ssl-key`,
+  `serve --backend ssh`, `session new --ssh` vs `--backend`, `--ssh-*` without
+  `--ssh`, unknown roles, and more. `config set` now type-checks the value
+  against the settings model and validates the whole file before writing.
+- **One set of user invariants for both surfaces** (`wsctl/core/user_admin.py`):
+  the CLI can no longer disable, demote or delete the last admin (which could
+  lock the instance out), and `wsctl user passwd` now revokes that user's
+  existing logins just like the API does.
+- **Consistent backups and restores**: `backup` uses SQLite's online backup API
+  (a WAL-mode database copied as a plain file could miss recent commits), and
+  `restore` validates the archive, refuses to overwrite without `--force`
+  (keeping a `.bak`), and rejects path-traversal members.
+- `wsctl connect` reconnects automatically with exponential backoff and
+  re-attaches to the same session (server-side replay restores the screen);
+  `--no-reconnect` opts out.
+- `doctor` now reports the running instance, port availability, `SO_REUSEPORT`
+  support and background-start capability.
+- Metrics `wsctl_audit_write_errors_total` and `wsctl_maintenance_lag_seconds`.
+
+### Changed
+
+- **WebSocket close codes are now meaningful**: `4400` bad request, `4401`
+  unauthenticated, `4403` forbidden, `4404` session not found, `4409` limit
+  reached, `4500` server error. The web client stops reconnecting on a permanent
+  failure instead of looping, and a missing session no longer pops the login
+  dialog at an already-authenticated user.
+- Session ids are hex (`token_hex`) so they can never start with `-` and be
+  mistaken for a CLI option.
+- `--reuse-port` now fails loudly when `SO_REUSEPORT` is unavailable instead of
+  silently binding without it (a silent downgrade would defeat zero-downtime
+  handovers).
+
+### Fixed
+
+- **Argon2 verification and hashing no longer run on the event loop**: login,
+  user creation and password changes run on a worker thread, so a login storm
+  cannot stall every terminal.
+- `Recorder.close()` (which joins its writer thread) no longer blocks the event
+  loop; retention purging, recording-capacity checks and directory listings run
+  on worker threads.
+- The audit writer survives a failing database write (it logs, counts and keeps
+  going instead of dying silently), and concurrent `flush()` calls can no longer
+  reorder events.
+- `serve --new` with a `tmux` backend that is not installed no longer crashes the
+  server at startup.
+- The web UI's Esc key closes the topmost modal (previously it could close the
+  admin panel behind the QR dialog), the QR dialog is a normal, focus-trapped
+  modal, password reset uses a masked input, and assigning a hotkey that is
+  already taken is rejected with a warning.
+
+### Testing
+
+- New suites for the validation layer, the pid-file lifecycle, consistent
+  backups/restores, and the shared user-admin invariants; WebSocket close-code
+  tests; audit-writer failure and ordering tests; a `daemon` end-to-end scenario;
+  and browser coverage for the 2FA QR modal.
+
+[0.1.3]: https://github.com/ThzxxArt/wsctl/releases/tag/v0.1.3
+
 ## [0.1.2] - 2026-09-22
 
 Polish and robustness release: disk/DB I/O is moved off the event loop, the web

{wsctl-0.1.2 → wsctl-0.1.4}/DESIGN.md

@@ -1,6 +1,6 @@
 # wsctl 设计文档
 
-> 版本：0.1.2 · 状态：0.1.0/0.1.1 已发布；0.1.2 待发布
+> 版本：0.1.4 · 状态：0.1.0–0.1.4 已发布
 > 作者：ThzxxArt · 许可：MIT
 
 ## 1. 定位
@@ -61,8 +61,11 @@ wsctl **不在原始吞吐上对标 ttyd**。纯 Python 无法在 `cat` 大文
 - **背压**：每个客户端维护有界发送队列；慢消费者达到上限时丢弃旧帧或断开，
   防止大输出导致服务端内存暴涨。
 - **回收策略**：空闲超时 / 最大生命周期 / 管理员显式 kill，三者之一触发回收。
-- **进程治理**：`start_new_session` + `killpg`，并在会话结束时 `wait()` 回收；未安装
-  全局 SIGCHLD handler（避免与 `subprocess` 争抢 PID）。已跟踪会话不残留僵尸进程。
+- **进程治理**：`start_new_session` + `killpg`，并在会话结束时 `wait()` 回收（**有界
+  等待，超时强杀**：子进程若被守护化孙进程占住终端而不退，也不能挂死清理路径）；
+  未安装全局 SIGCHLD handler（避免与 `subprocess` 争抢 PID）。已跟踪会话不残留僵尸进程。
+- **分享也是承诺**：share token / 有效期 / 可写标记与会话一起持久化，服务重启后原样
+  恢复（不轮换 token），已分发的二维码与链接继续可用；重命名会话不会使其失效。
 
 ### 3.1 可选 tmux 后端（跨重启恢复）
 
@@ -134,7 +137,9 @@ users(id, username, password_hash, role[admin|user], totp_secret, disabled, crea
 auth_sessions(id, user_id, token_hash, ip, user_agent, exp, last_seen)   -- 登录态
 
 term_sessions(id, name, owner_id, backend[local|tmux|ssh], command, argv, env,
-              cwd, idle_timeout, max_life, status, instance_id, created_at, last_active)
+              cwd, idle_timeout, max_life, status, instance_id,
+              share_token, share_expires, share_writable,
+              created_at, last_active)
 
 instances(id, pid, host, started_at, heartbeat)          -- 多实例租约
 
@@ -145,27 +150,45 @@ settings(key, value)
 
 > 命名约定：`auth_sessions` 指**登录态**，`term_sessions` 指**终端会话**，
 > `instances` 指**服务进程租约**。
-> 模式版本 3；旧库通过 `PRAGMA table_info` + `ALTER TABLE` 幂等迁移补齐新列，且索引
+> 模式版本 4；旧库通过 `PRAGMA table_info` + `ALTER TABLE` 幂等迁移补齐新列，且索引
 > 在列补齐之后创建（否则升级旧库会因列不存在而失败）。
+>
+> `share_token` / `share_expires` / `share_writable` 持久化分享链接：分享是**承诺**，
+> 必须和会话一样跨重启存活（0.1.4 起）。降级到 0.1.3 及更早版本前请先 `wsctl backup`，
+> 旧版本不认识这几列。
 
 ## 6. CLI 命令树（已实现）
 
 ```
-wsctl serve                     # 起控制面，默认配置开箱即用
+wsctl serve                     # 前台起服务（--daemon 转后台）
+wsctl start|stop|restart|status|logs|reload   # 非 systemd 后台生命周期
 wsctl serve --new "bash"        # 启动时顺带开一个会话
 wsctl serve --backend tmux      # 默认使用 tmux 后端（跨重启恢复）
-wsctl doctor                    # 环境与配置自检
-wsctl session list|new|rename|kill|attach   # new 支持 --backend local|tmux|ssh
+wsctl doctor                    # 环境、配置、运行状态、端口、SO_REUSEPORT、磁盘、时钟自检
+wsctl session list|new|rename|kill|attach   # 均支持 --json；new 支持 --backend local|tmux|ssh
 wsctl session record|record-stop|recording
-wsctl connect [url] [-s id]     # 瘦客户端：本地 raw 终端直连
-wsctl login|logout              # 缓存/清除服务端凭据
+wsctl connect [url] [-s id]     # 瘦客户端：本地 raw 终端直连（断线自动重连）
+wsctl login|logout              # login 支持 --totp / WSCTL_TOTP（两步验证账号）
 wsctl user add|list|del|passwd|role|disable|enable|totp
-wsctl audit                     # 查看审计日志（admin）
-wsctl config show|path|edit|set|reload
+wsctl audit [--event|--user-id|--ip|--json]
+wsctl backup FILE [--include-config] / restore FILE [--force]
+wsctl config show|get|path|edit|set|validate|reload    # set 保留行内注释
+wsctl completion install|show [bash|zsh|fish|powershell]
 wsctl version / --version
 ```
 
-> `config set` 写入配置文件（校验 TOML），`config reload` 让运行中的服务热加载。
+> `config set` 写入前会校验单项类型与整文件合法性（不合法则拒绝并回滚），并保留被改行
+> 尾部的注释；`config reload`（或 `wsctl reload` 的 SIGHUP）让运行中的服务热加载，
+> **配置写错时会原样打印错误并以非零码退出**，绝不静默忽略。
+>
+> **互斥/依赖强校验**：所有互相冲突或彼此依赖的参数在 `cli/validate.py` 中声明式
+> 定义，非法组合在进程启动前即以退出码 2 报错，而不是静默忽略其一。
+>
+> **后台生命周期**（`cli/daemon.py`）：子进程以 `start_new_session` 脱离终端，
+> stdout/stderr 重定向到 `<data_dir>/run/wsctl-<port>.log`（可按大小轮转，
+> copytruncate 语义以保住继承的追加型描述符）；pid 文件记录
+> **进程身份指纹**（Linux 取 `/proc/<pid>/stat` 的 starttime），`stop/status` 在
+> 发信号前核对，避免 PID 复用误杀。`--reuse-port` 的多实例热切换不纳入托管。
 
 
 ## 7. 目录结构
@@ -246,8 +269,21 @@ pyotp  segno  websockets
 | **M25** | 0.1.2 便捷性：`config get/validate`、`doctor --json`、`backup`、终端内 TOTP 二维码、shell 补全、Docker 示例 |
 | **M26** | 0.1.2 设计系统：令牌 + 组件、图标化工具栏 + 移动端折叠、统一 Modal、主题色预览、favicon/manifest、空态/加载态、a11y、跟随系统深浅色 |
 | **M27** | 0.1.2 测试与文档：异步审计/管理 API/TOTP/节流/滑动 TTL 单测 + 浏览器用例扩展；README/DESIGN/CHANGELOG 同步 |
-
-## 10.1 实现状态（截至 0.1.2）
+| **M28** | 0.1.3 非 systemd 后台生命周期：`start/stop/restart/status/logs/reload`（`start --force` 先停再启）+ `serve --daemon`；pidfile（进程身份指纹）+ 日志文件 + stale-pid 清理；SIGHUP 配置重载；Windows 明确不支持 |
+| **M29** | 0.1.3 参数互斥/依赖强校验：`cli/validate.py` 声明式规则（conflicts/requires/requires_if/choices）；`config set` 类型与整文件校验 + 回滚；`serve --backend`/`--ssl-*`/`--daemon`/`--reuse-port` 组合约束；`--reuse-port` 在平台不支持 `SO_REUSEPORT` 时**明确报错**而非静默降级 |
+| **M29b** | 0.1.3 用户管理不变量同源：`core/user_admin.py`，CLI 与 API 共用（最后管理员保护、不能操作自身、改密/禁用即吊销登录态） |
+| **M30** | 0.1.3 事件循环解阻：argon2 认证/建用户/改密移出循环、`Recorder.close` 非阻塞、保留清理/录制容量/目录列举入线程、AuditWriter 容错与 flush 串行化、维护滞后指标 |
+| **M31** | 0.1.3 连接健壮性：WS 关闭码语义化（4400/4401/4403/4404/4408 空闲超时/4409/4500）+ 前端按码处理（永久失败不再重连、会话不存在不再误弹登录框）；**半开连接检测**（服务端 120s 无消息回收，前端与 CLI 每 25s 心跳）；`connect` 客户端指数退避自动重连；会话 id 改十六进制（避免以 `-` 开头被当选项） |
+| **M32** | 0.1.3 一致性备份/恢复：`backup` 用 SQLite 在线备份 API（含 WAL）、`restore` 校验归档/拒绝穿越/`--force` 保留 `.bak`；`status --json`；`doctor` 扩展运行状态/端口/reuse-port/后台能力 |
+| **M33** | 0.1.3 前端易用性：密码掩码对话框、QR 弹窗纳入统一 Modal（Esc 关最上层/焦点陷阱）、快捷键冲突检测 |
+| **M34** | 0.1.3 测试与文档：校验层/daemon 生命周期/备份恢复/用户不变量单测 + 关闭码测试 + e2e `daemon` 场景 + 浏览器 QR 用例；README/DESIGN/CHANGELOG 同步 |
+| **M35** | 0.1.4 「说到做到」：CLI TOTP 登录（`--totp`/`WSCTL_TOTP`/交互补录）、密码策略（非空+≥8 位，`core/passwords` 单一入口，Store/user_admin 双闸，不强制改存量）、`_finalize` 有界等待 + 强杀（子进程不退也不再挂死）、**分享 token 持久化**（schema v4 + 收养回填 + 过期清理）、录制诚实性（写失败自闭 + `close` 与写线程互斥）、配置热加载报错（`(changed, errors)` 贯通 API/CLI/日志）、Argon2 惰性化 |
+| **M36** | 0.1.4 「长跑不塌」：认证短缓存（`core/authcache.py`，改密/禁用/改角色即时失效）+ 同步 SQLite 全面出事件循环（WS 握手与周期复查、维护循环批量写、audit/users 查询）、PTY 写缓冲满**反馈**（一次性提示 + `wsctl_pty_input_dropped_total`）、日志轮转（copytruncate 保住继承的追加型 fd）、Web 惰性连接（最多 8 个在线，其余「未连接」按需挂载）、上传防覆盖（409 + 确认后 `overwrite=1`）、`list_dir` 上限 + 截断标记、`connect` 非 JSON 文本帧容错、metrics 标签转义、scrollback UTF-8 边界对齐 |
+| **M37** | 0.1.4 「脚本与界面顺手」：CLI 全线 `--json`（session/user/audit/config show）+ `audit` 筛选 + `session list` 显示用户名/后端/存活、Web 建会话对话框（名称/命令/工作目录/后端/结构化 SSH 表单 + 必填校验）、Web 管理面「配置」页签（`GET /api/config`，标注热更新/需重启 + 重载反馈）、`config set` 保留行内注释且不误改注释行、`wsctl completion install|show`（bash/zsh/fish/powershell，按 `$SHELL` 探测）、`doctor` 增检磁盘/密码策略/日志/系统时钟、CLI 冷启动懒加载（`wsctl version` 1.05s → 0.36s） |
+| **M38** | 0.1.4 部署与工程化：Docker 改**仓库根构建**（装本地源码而非 PyPI 旧版）+ `entrypoint.sh` 首启建号 + compose 强制 `WSCTL_ADMIN_PASSWORD` + `.dockerignore`、CI 加 macOS 腿与 Windows 导入/CLI 冒烟、`-m slow` 压测入 CI、装 `lrzsz` 真机验证 ZMODEM 收发、构建 Docker 镜像冒烟、systemd 单元注明 `ExecStart` 路径来源、e2e 失败时打印子进程日志 |
+| **M39** | 0.1.4 测试与文档：新增密码策略/认证缓存/日志轮转/录制失败/UTF-8/metrics 转义六个套件，扩展分享持久化、有界 `Pty.wait`、PTY 丢输入、上传覆盖、配置端点与重载报错、TOTP/`--json`/注释保留/补全；浏览器覆盖建会话对话框、配置页签、上传覆盖提示、连接预算、**ZMODEM `sz`/`rz` 字节级真机往返**；e2e 断言分享跨重启存活；README/DESIGN/CHANGELOG/SECURITY 同步 |
+
+## 10.1 实现状态（截至 0.1.4）
 
 **已实现**：M0–M20 全部交付项；二进制 WS 协议、会话与连接解耦、重连回放、
 多用户 RBAC、审计 + `/api/audit`、登录限速、IP allowlist、TOTP、安全响应头、
@@ -259,8 +295,22 @@ asciinema 录制 + 前端回放、SO_REUSEPORT 零停机重启、Webhook、
 `config set`/`reload`、前端浏览器级自动化测试、每会话内存硬上限、
 Sixel 渲染、可选 ZMODEM、终端主题市场。
 
-**尚未实现**：无。唯一验证缺口：ZMODEM 的真实 `rz`/`sz` 传输未在 CI 端到端跑通
-（环境无 lrzsz），仅验证了集成不破坏常规终端 I/O。
+**0.1.3 新增**：非 systemd 后台生命周期（pidfile + 身份指纹 + 日志文件 + SIGHUP
+重载）、声明式参数互斥/依赖强校验、CLI 与 API 同源的用户管理不变量、一致性
+备份/恢复（SQLite 在线备份）、WS 关闭码语义化、`connect` 自动重连、事件循环
+解阻（argon2/录制/保留/审计容错）。
+
+**0.1.4 新增**：承诺闭环与可靠性收口——**分享链接跨重启存活**（与会话同级的承诺）、
+CLI 两步验证登录、密码策略、子进程不退也不挂死、录制失败自诚实、配置写错必报错、
+认证查询出事件循环 + 短缓存、日志轮转、上传防覆盖、Web 连接预算与 SSH 建会话表单、
+CLI 全线 `--json`、多 shell 补全。**验证深度提升**：ZMODEM 从「集成不破坏 I/O」升级为
+**`sz`/`rz` 字节级真机往返**。
+
+**尚未实现**：无。验证边界（诚实声明）：
+- ZMODEM 真机往返需要 `lrzsz`（CI 已装并执行；本地缺失时该浏览器用例跳过）。
+- 后台生命周期为 POSIX-only；Windows 下 `serve --daemon`/`start` 明确报错并建议
+  服务管理器，CI 仅做导入与 CLI 冒烟（`wsctl[win]` 的 `WinPty` 未端到端验证）。
+- Docker 镜像构建在 CI 的 `docker` job 中验证；本机无 docker 时未构建过。
 
 > 0.1.1 起，关闭标签默认只断开连接（detach），终止会话需显式操作（右键菜单 /
 > 会话列表 / `Alt+Shift+W`），与「会话独立于连接」的核心承诺一致。
@@ -268,19 +318,26 @@ Sixel 渲染、可选 ZMODEM、终端主题市场。
 > 0.1.2 起，磁盘/数据库写入全部移出事件循环：审计经 `AuditWriter` 队列批量落盘，
 > 录制在后台线程写文件，上传在线程池落盘；`resolve_auth_session` 节流 `last_seen`。
 
-> 回归测试：`scripts/e2e/run_all.py` 提供 7 个后端端到端场景（server / CLI /
-> connect / tmux 重启恢复 / crash 崩溃收养 / **multiplex 多实例隔离** /
-> SO_REUSEPORT 优雅重启）；`pytest -m browser` 为浏览器级测试；
-> `pytest -m slow` 为并发/大输出压测。CI 在独立 job 中运行浏览器测试。
+> 0.1.4 起，**读路径**同样出事件循环：WS 握手与周期复查、维护循环的租约/回收/保留、
+> 审计与用户查询均在线程池执行；`resolve_auth_session` 前置一层短缓存
+> （`core/authcache.py`），改密/禁用/改角色/删除时主动失效对应条目，因此
+> 「禁用用户立即踢线」的语义不变。
+
+> 回归测试：`scripts/e2e/run_all.py` 提供 8 个后端端到端场景（server / CLI /
+> connect / tmux 重启恢复 **含分享跨重启存活断言** / crash 崩溃收养 /
+> **multiplex 多实例隔离** / **daemon 后台生命周期** / SO_REUSEPORT 优雅重启）；
+> `pytest -m browser` 为浏览器级测试（含 ZMODEM 真机往返）；`pytest -m slow`
+> 为并发/大输出压测。CI 在独立 job 中运行浏览器测试、慢速压测与 Docker 构建。
 
 > 说明：进程回收依赖 `start_new_session` + `killpg` 与 `TermSession` 结束时的
-> `wait()`，未安装全局 SIGCHLD handler（避免与 `subprocess` 争抢 PID）；已跟踪
-> 会话不会残留僵尸进程。
+> `wait()`（**有界等待，超时强杀**），未安装全局 SIGCHLD handler（避免与
+> `subprocess` 争抢 PID）；已跟踪会话不会残留僵尸进程。
 
 ## 11. Backlog（后续）
 
-无（v0.1.2 计划项已全部落地）。后续可考虑：ZMODEM 真机端到端测试、
-每用户后端策略（命令级权限隔离）、i18n 框架、更多终端协议（Kitty graphics 等）。
+无（v0.1.4 计划项已全部落地）。后续可考虑：每用户后端策略（命令级权限隔离）、
+i18n 框架、更多终端协议（Kitty graphics 等）、Windows 服务封装与 `WinPty`
+端到端验证、`--reuse-port` 实例的托管。
 
 ## 12. 发布