abruption · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,11 +1,17 @@
 # Changelog
 
-## v0.3.1 — unreleased
+## v0.3.1 — 2026-10-19
 
+- Wait for transient startup backend states within a bounded readiness deadline and distinguish authentication, approval and query failures (#25).
+- Explain read-only installation/runtime access and socket visibility in the current execution context, with safe GUI-terminal guidance (#26).
 - Validate and retain the proxy apply log descriptor before stopping the current daemon, including rollback launches (#32).
 - Preserve upstream CONNECT response remainder bytes in raw tunnels (#33).
 - Reject malformed upstream WebSocket frames before forwarding payloads or sending pong responses (#34).
 
+These fixes were merged in [PR #35](https://github.com/abruption/dots-tailscale/pull/35). The final combined candidate passed all 178 offline tests on Linux Python 3.11/3.13; focused proxy, shim, CLI and readiness suites also passed on actual Python 3.8/3.13. The candidate has not been deployed to Dots. Startup-readiness [PR #36](https://github.com/abruption/dots-tailscale/pull/36) and execution-context diagnostics [PR #37](https://github.com/abruption/dots-tailscale/pull/37) are merged and included in this release.
+
+See the [release preparation notes](docs/releases/v0.3.1.md).
+
 ## v0.3.0 — 2026-10-18
 
 - Add `dots-ts cli` for socket-aware Tailscale commands and a read-only `doctor` that reports installation, process, socket, backend, proxy and optional TCP reachability separately.

diff --git a/README.ko.md b/README.ko.md
@@ -26,7 +26,7 @@ Linux x86_64, Git, Python 3, OpenSSH와 사용자 계정의 22번 포트 바인
 ```bash
 cd /workspace
 HTTPS_PROXY=http://browser-proxy:8889 HTTP_PROXY=http://browser-proxy:8889 \
-  git clone --branch v0.3.0 --depth 1 https://github.com/abruption/dots-tailscale.git
+  git clone --branch v0.3.1 --depth 1 https://github.com/abruption/dots-tailscale.git
 cd dots-tailscale
 bash tailscale-setup.sh check
 bash tailscale-setup.sh install
@@ -35,9 +35,9 @@ bash /workspace/.dots-tailscale/start.sh login
 
 최초 로그인 URL을 승인한 뒤 SSH 공개키를 설치 경로의 `authorized_keys`에 등록하세요. 호스트 키 지문은 클라우드 컴퓨터의 GUI 터미널에서 확인한 후 SSH로 접속합니다. 환경이 교체되면 `bash /workspace/.dots-tailscale/start.sh`로 기존 설치를 수동 기동하세요.
 
-## v0.3.0: 진단과 비공개 HTTP 접속
+## v0.3.1: 진단과 비공개 HTTP 접속
 
-아래 도구를 사용하려면 [v0.3.0](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.0)의 소스 파일 네 개를 함께 설치하세요.
+아래 도구를 사용하려면 [v0.3.1](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.1)의 소스 파일 네 개를 함께 설치하세요.
 
 ```bash
 /workspace/.dots-tailscale/dots-ts doctor

diff --git a/README.md b/README.md
@@ -26,7 +26,7 @@ The clone command explicitly uses the Dots proxy because direct GitHub HTTPS fai
 ```bash
 cd /workspace
 HTTPS_PROXY=http://browser-proxy:8889 HTTP_PROXY=http://browser-proxy:8889 \
-  git clone --branch v0.3.0 --depth 1 https://github.com/abruption/dots-tailscale.git
+  git clone --branch v0.3.1 --depth 1 https://github.com/abruption/dots-tailscale.git
 cd dots-tailscale
 bash tailscale-setup.sh check
 bash tailscale-setup.sh install
@@ -35,9 +35,9 @@ bash /workspace/.dots-tailscale/start.sh login
 
 The first login prints an approval URL. Add the client public key to the installed SSH `authorized_keys` file and verify the host-key fingerprint over the cloud computer's GUI terminal before connecting. After environment replacement, start the existing installation with `bash /workspace/.dots-tailscale/start.sh`. The scripts do not register automatic startup.
 
-## v0.3.0: diagnostics and private HTTP access
+## v0.3.1: diagnostics and private HTTP access
 
-Install all four source files from [v0.3.0](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.0) to use these helpers.
+Install all four source files from [v0.3.1](https://github.com/abruption/dots-tailscale/releases/tag/v0.3.1) to use these helpers.
 
 ```bash
 /workspace/.dots-tailscale/dots-ts doctor

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.3.0
+0.3.1
diff --git a/docs/releases/v0.3.1.md b/docs/releases/v0.3.1.md
@@ -0,0 +1,55 @@
+# v0.3.1 release preparation
+
+Release preparation record for v0.3.1. The implementation PRs and the integrated candidate were reviewed before publication. Tag creation, asset validation and publication follow the checklist below; installed environments require a separate explicit deployment.
+
+## Release summary
+
+v0.3.1 includes startup-readiness and execution-context diagnostics (#25/#26), together with three proxy/transport fixes from [PR #35](https://github.com/abruption/dots-tailscale/pull/35):
+
+- **Startup readiness (#25):** wait for transient backend states within an overall deadline and distinguish authentication, approval and query failures.
+- **Execution-context diagnostics (#26):** report read-only filesystem/access and socket visibility in the current context, with independent GUI-terminal guidance.
+- **Proxy apply and recovery (#32):** open and validate the private log before stopping the current daemon. Replacement and rollback reuse the same descriptor even if the path changes.
+- **CONNECT data preservation (#33):** forward raw tunnel bytes buffered with the upstream response exactly once and in order. For TLS interception on port443, reject unexpected pre-handshake bytes before reporting success rather than discard them.
+- **WebSocket framing (#34):** reject masked/reserved-bit frames, invalid control frames, malformed lengths and continuation sequences before forwarding their payloads or sending pong. Valid fragmentation and interleaved control frames remain supported.
+
+Tailscale remains **1.102.4**. Installation still requires all four source files together: `tailscale-setup.sh`, `shim.py`, `dots-ts` and `dots_proxy.py`. Installation state and keys must be preserved during staged upgrades.
+
+## Verification and remaining scope
+
+- [Implementation CI](https://github.com/abruption/dots-tailscale/actions/runs/39201120437) passed **157** tests on each of Python3.11 and3.13, plus Bash syntax/ShellCheck.
+- [Combined candidate CI](https://github.com/abruption/dots-tailscale/actions/runs/39205008955) passed all **178** tests on Linux Python 3.11/3.13 after the explicit-login/approval follow-up. [PR #36 re-review](https://github.com/abruption/dots-tailscale/pull/36#issuecomment-6260462216) and [PR #38 re-review](https://github.com/abruption/dots-tailscale/pull/38#issuecomment-6260469116) reported no additional findings.
+- Focused proxy tests: 34 total, one Linux-only skip on macOS; focused shim tests: 45 passed, on actual Python3.8 and3.13.
+- [Codex review of the final implementation commit](https://github.com/abruption/dots-tailscale/pull/35#issuecomment-6259931703) reported no major issues. The Linux reset/EOF finding was addressed in `89e0f37`.
+- Process-control tests use inert mocks and disposable files. Shim tests use isolated transports/socket peers. No live deployment or forced outage is established by these results.
+- The current 24-hour watchdog experiment belongs to #20 and uses the installed v0.3.0 environment; its pending results are not v0.3.1 deployment evidence.
+- **#25 and #26 are included.** [PR #36](https://github.com/abruption/dots-tailscale/pull/36) and [PR #37](https://github.com/abruption/dots-tailscale/pull/37) were reviewed, passed CI and merged before the release preparation PR.
+- VM replacement recovery, permanent automatic startup and automatic updates are not provided. No full WebSocket text UTF-8/close-status validation or new frame memory limit is claimed.
+
+## Publication checklist
+
+- [x] Review and merge the #25 and #26 implementation PRs, then review this preparation PR against the final combined code.
+- [ ] Merge the selected release scope, confirm `VERSION=0.3.1`, and require passing checks on the exact final commit.
+- [ ] Create an annotated `v0.3.1` tag on that commit when publication is authorized. Verify an existing tag; never move it to hide a changed release.
+- [ ] Package the reviewed tag only: `dots-tailscale-v0.3.1.zip`, `dots-tailscale-v0.3.1.tar.gz`, plus the four individual source files.
+- [ ] Compare archive source bytes with the individual files; generate `SHA256SUMS` and attach it as the seventh asset. Exclude workspace state, local untracked files, credentials, certificates and logs.
+- [ ] Create/review a draft release, attach the seven assets and publish only after its exact tag/asset digests and notes are checked.
+- [ ] Verify public links, latest-release selection and uploaded asset hashes. Date the changelog using the actual publication date.
+
+Suggested archive commands after the tag exists, in Bash with `set -euo pipefail` and a pre-created private absolute `artifact_dir`:
+
+```bash
+git archive --format=zip --prefix=dots-tailscale-v0.3.1/ \
+  --output="$artifact_dir/dots-tailscale-v0.3.1.zip" v0.3.1
+git archive --format=tar.gz --prefix=dots-tailscale-v0.3.1/ \
+  --output="$artifact_dir/dots-tailscale-v0.3.1.tar.gz" v0.3.1
+for file in tailscale-setup.sh shim.py dots-ts dots_proxy.py; do
+  git show "v0.3.1:$file" > "$artifact_dir/$file"
+done
+(
+  cd "$artifact_dir"
+  sha256sum dots-tailscale-v0.3.1.zip dots-tailscale-v0.3.1.tar.gz \
+    tailscale-setup.sh shim.py dots-ts dots_proxy.py > SHA256SUMS
+)
+```
+
+Publishing does not upgrade Dots automatically. A deployed update needs its own staged backup/restart/rollback procedure and external strict-host-key SSH verification.