feat: report installed package version and source integrity

.github/workflows/checks.yml

@@ -33,6 +33,8 @@ jobs:
             sudo apt-get update
             sudo apt-get install --yes openssh-client openssh-server
           fi
+      - name: Check source manifest
+        run: python scripts/source_manifest.py --check
       - name: Run offline tests
         run: python -m unittest discover -s tests -v
 

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased — v0.4.0 development
+
+- Add offline `dots-ts version` reporting for package identity, source-file integrity and the separate Tailscale binary version (#27).
+- Require a matching source manifest for new installations; preserve unknown metadata for legacy installations instead of guessing a version.
+- Add package integrity to `doctor` and document the development feature in all four languages.
+
+This development work has not been deployed to Dots. Release checks, notifications and verified updates remain separate work in #28–#30.
+
 ## 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).

README.ja.md

@@ -47,6 +47,10 @@ bash /workspace/.dots-tailscale/start.sh login
 
 `doctor` は状態を変更せず、ローカルの診断情報を読み取ります。`cli` はインストール済みの Tailscale バイナリとソケットを選択します。任意で使える loopback SOCKS5/HTTP プロキシは既定で無効です。有効にするには、デーモンを再起動する手順を別途確認してください。設定、アクセス方針、検証範囲については、[使用ガイド](docs/usage.ja.md#development-helpers)と[プライベート HTTP API の利用例](docs/private-http-api.ja.md)を参照してください。これらのプロキシは ChatGPT コネクター、MCP クライアント、Dots ブラウザーには自動設定されません。
 
+## 開発中：インストール済みパッケージのバージョン確認
+
+開発版では `dots-ts version` と `dots-ts version --json` で、dots-tailscale パッケージと Tailscale バイナリのバージョンを別々に確認できます。v0.3.1 にはまだ含まれていません。詳しくは[パッケージのバージョンとファイルの確認](docs/usage.ja.md#package-version)を参照してください。
+
 ## 同梱内容
 
 | パス | 用途 |

README.ko.md

@@ -47,6 +47,10 @@ bash /workspace/.dots-tailscale/start.sh login
 
 `doctor`는 상태를 바꾸지 않고 로컬 진단 정보를 읽습니다. `cli`는 설치된 Tailscale 실행 파일과 소켓을 선택합니다. 선택 기능인 로컬 SOCKS5·HTTP 프록시는 기본적으로 꺼져 있으며, 활성화하려면 데몬 재시작을 별도로 검토해야 합니다. 설정과 접근 정책, 검증 범위는 [사용 가이드](docs/usage.ko.md#development-helpers)와 [비공개 HTTP API 연결 예시](docs/private-http-api.ko.md)를 참고하세요. ChatGPT 커넥터·MCP 클라이언트·Dots 브라우저에 자동으로 적용되지는 않습니다.
 
+## 개발 중: 설치된 패키지 버전 확인
+
+개발 버전의 `dots-ts version`과 `dots-ts version --json`은 dots-tailscale 패키지 버전과 내부 Tailscale 버전을 따로 보여줍니다. v0.3.1에는 아직 없는 명령입니다. 자세한 내용은 [패키지 버전과 파일 확인](docs/usage.ko.md#package-version)을 참고하세요.
+
 ## 구성 요소
 
 | 경로 | 역할 |

README.md

@@ -47,6 +47,10 @@ Install all four source files from [v0.3.1](https://github.com/abruption/dots-ta
 
 `doctor` reads local diagnostics without changing state. `cli` selects the installed Tailscale binary and socket. Optional loopback SOCKS5/HTTP proxies are disabled by default and require a separately reviewed daemon restart to enable. See the [usage guide](docs/usage.md#development-helpers) and [private HTTP API recipe](docs/private-http-api.md) for configuration, access policy, and validation limits. These proxies do not automatically configure ChatGPT connectors, MCP clients, or the Dots browser.
 
+## Development: installed package version
+
+The development build adds `dots-ts version` and `dots-ts version --json` to show the dots-tailscale package version separately from the Tailscale binary version. These commands are not included in v0.3.1. See [package version and file verification](docs/usage.md#package-version).
+
 ## Included
 
 | Path | Purpose |

README.zh-CN.md

@@ -47,6 +47,10 @@ bash /workspace/.dots-tailscale/start.sh login
 
 `doctor` 读取本地诊断信息，不会更改状态。`cli` 会选择已安装的 Tailscale 二进制文件和套接字。可选的回环 SOCKS5/HTTP 代理默认关闭；启用前需要单独审查并重启守护进程。配置、访问策略和验证范围请参阅[使用指南](docs/usage.zh-CN.md#development-helpers)和[私有 HTTP API 配置示例](docs/private-http-api.zh-CN.md)。这些代理不会自动配置 ChatGPT 连接器、MCP 客户端或 Dots 浏览器。
 
+## 开发中：查看已安装的软件包版本
+
+开发版新增了 `dots-ts version` 和 `dots-ts version --json`，可以分别查看 dots-tailscale 软件包版本和 Tailscale 程序版本。v0.3.1 尚不包含这些命令。详情见[软件包版本与文件校验](docs/usage.zh-CN.md#package-version)。
+
 ## 项目内容
 
 | 路径 | 用途 |

VERSION

@@ -1 +1 @@
-0.3.1
+0.4.0-dev

docs/usage.ja.md

@@ -138,6 +138,27 @@ backend の準備確認では、各フェーズにつき単調時計で計る30
 
 このリポジトリには VM cron、systemd サービス、自動起動登録はありません。Dots オートメーション経由の起動も未検証です。VM 内のプロセスループは、その環境が破棄されると存続できません。新しい環境でインストールを明示的に起動するか、別途検証済みのプラットフォーム実行手段を使ってください。
 
+<a id="package-version"></a>
+
+## パッケージのバージョンとファイルの確認（開発中）
+
+v0.4.0 に向けて開発中の機能です。上記の v0.3.1 のインストール例には含まれません。新しいリリースを公開しても、既存のインストールは自動で更新されません。
+
+```bash
+/workspace/.dots-tailscale/dots-ts version
+/workspace/.dots-tailscale/dots-ts version --json
+```
+
+GitHub や tailnet には接続せず、ローカルのパッケージファイルを確認します。マニフェストに記載されたパッケージのバージョン、ソースファイルの一致状況、インストール済み Tailscale バイナリのバージョンを別々に表示します。ソースのリビジョンが不明なら、そのまま不明として扱います。マニフェストとの一致はファイルの整合性を示しますが、配布元の本人確認や、動作中のサービスが正常であることの証明にはなりません。
+
+確認済みの同じリビジョンから取得したソースファイル 4 つと `source-manifest.json` を一緒に用意してください。新しいインストーラーはこの組み合わせを検証し、マニフェストをインストール先に保存します。不一致を消すために、変更済みのインストールファイルから期待するハッシュを作り直さないでください。メタデータのない既存の v0.2/v0.3 環境では、パッケージのバージョンは不明になります。Tailscale のバージョンだけでは判別できません。
+
+更新やロールバックの際は、ソースファイルと対応する元のマニフェストをセットで保管し、一緒に入れ替えてください。古いコードに新しいマニフェストだけを上書きしないでください。ノードの状態、秘密鍵、SSH の識別情報、プロキシ設定は保持します。以下の手動更新の注意事項も引き続き適用されます。このコマンド自体は更新や再起動を行いません。
+
+JSON では `package.declared_version`、`package.source_revision`、`package.integrity` とファイルごとの結果を、`tailscale.version`、`tailscale.status` と分けて表示します。整合性は `match`、`mismatch`（変更または異なるバージョンの混在）、`incomplete`（ファイルの欠落または読み取り不可）、`unknown`（メタデータの欠落、不正または読み取り不可）のいずれかです。`source_revision` は現在 `null` で、コミットを推測しません。mismatch/incomplete の終了コードは `1`、それ以外は `0` です。終了コード `0` だけではバージョンが判明したことや Tailscale バイナリが利用可能であることを示しません。`doctor` はメタデータが不明なら degraded、ファイルの不一致や不足は unhealthy と表示します。
+
+メンテナンス時は、確認済みのソース変更後に `python3 scripts/source_manifest.py` を実行し、差分を確認してから `python3 scripts/source_manifest.py --check` で検証します。CI はファイルを書き換えず、検証のみ行います。生成は確認済みのソースチェックアウトで行い、インストール先では行わないでください。リリースにはソースファイル 4 つに対応するマニフェストも含める必要があります。既存の v0.3.1 リリースには含まれていません。
+
 <a id="development-helpers"></a>
 
 ## v0.3.1 ヘルパーと任意のアプリケーションプロキシ

docs/usage.ko.md

@@ -87,6 +87,27 @@ ssh -o StrictHostKeyChecking=ask -i /path/to/client_private_key 'agent@<TAILNET_
 
 승인한 뒤에는 `ssh -o StrictHostKeyChecking=yes -i /path/to/client_private_key 'agent@<TAILNET_IP>' 'id; pwd'`로 접속할 수 있습니다. 사용자명과 SSH 키 경로는 자신의 설정에 맞게 지정하세요. 이후 지문이 달라지면 Dots GUI 터미널에서 다시 확인하세요.
 
+<a id="package-version"></a>
+
+## 패키지 버전과 파일 확인 (개발 중)
+
+v0.4.0을 위해 개발 중인 기능입니다. 위의 v0.3.1 설치 예시에는 포함되지 않습니다. 새 릴리스를 발행해도 기존 설치가 자동으로 바뀌지는 않습니다.
+
+```bash
+/workspace/.dots-tailscale/dots-ts version
+/workspace/.dots-tailscale/dots-ts version --json
+```
+
+GitHub나 tailnet에 접속하지 않고 로컬 패키지 파일을 확인합니다. 명세 파일에 적힌 패키지 버전, 소스 파일 일치 여부, 설치된 Tailscale 실행 파일의 버전을 각각 보여줍니다. 소스 리비전을 알 수 없으면 그대로 알 수 없다고 표시합니다. 파일이 명세와 일치한다고 해서 배포자의 신원이나 실행 중인 서비스의 정상 동작까지 증명되는 것은 아닙니다.
+
+같은 검토된 리비전의 소스 파일 네 개와 `source-manifest.json`을 함께 준비하세요. 새 설치기는 이 묶음을 검증한 뒤 명세를 설치 경로에 보존합니다. 불일치를 없애려고 수정된 설치 파일로 기대 체크섬을 다시 만들면 안 됩니다. 메타데이터가 없는 기존 v0.2/v0.3 설치는 패키지 버전을 알 수 없다고 표시합니다. 내부 Tailscale 버전만으로 패키지 버전을 판단할 수는 없습니다.
+
+업데이트나 원복을 준비할 때는 소스 파일과 해당 원본 명세를 한 묶음으로 보관하고 함께 교체하세요. 오래된 코드에 새 명세만 덮어쓰지 마세요. 노드 상태, 개인키, SSH 식별 정보와 프록시 설정은 보존합니다. 아래 수동 업데이트 주의사항도 그대로 적용됩니다. 이 명령 자체는 업데이트하거나 재시작하지 않습니다.
+
+JSON은 `package.declared_version`, `package.source_revision`, `package.integrity`, 파일별 결과를 `tailscale.version` 및 `tailscale.status`와 구분합니다. 일치 여부는 `match`, 수정되거나 다른 버전이 섞인 `mismatch`, 파일이 없거나 읽을 수 없는 `incomplete`, 메타데이터가 없거나 잘못됐거나 읽을 수 없는 `unknown`으로 표시합니다. `source_revision`은 현재 `null`이며 커밋을 추측하지 않습니다. mismatch/incomplete는 종료 코드 `1`, 나머지는 `0`입니다. 따라서 종료 코드 `0`만으로 버전을 확인했거나 Tailscale 실행 파일이 정상이라고 판단하면 안 됩니다. `doctor`는 메타데이터를 알 수 없으면 degraded, 파일 불일치·누락은 unhealthy로 표시합니다.
+
+유지보수 시에는 검토한 소스 변경 후 `python3 scripts/source_manifest.py`로 명세를 생성하고 차이를 확인한 뒤 `python3 scripts/source_manifest.py --check`로 검사합니다. CI는 파일을 수정하지 않고 검사만 합니다. 설치 경로가 아닌 검토된 소스 체크아웃에서만 생성하세요. 릴리스에는 소스 파일 네 개와 일치하는 명세도 함께 배포해야 합니다. 기존 v0.3.1 릴리스에는 이 명세가 없습니다.
+
 <a id="development-helpers"></a>
 
 ## v0.3.1 도구와 선택적 애플리케이션 프록시

docs/usage.md

@@ -138,6 +138,27 @@ The custom TLS/WebSocket shim implements the configured local HTTP CONNECT bridg
 
 There is no VM cron, systemd service, or automatic startup registration in this repository. Startup through Dots automation has not been tested. A process loop inside the VM cannot survive destruction of that environment. Start the installation explicitly in a new environment or through a separately verified platform execution mechanism.
 
+<a id="package-version"></a>
+
+## Package version and file verification (development)
+
+This feature is in development for v0.4.0; the v0.3.1 installation examples above do not include it. Publishing a release does not upgrade an existing installation.
+
+```bash
+/workspace/.dots-tailscale/dots-ts version
+/workspace/.dots-tailscale/dots-ts version --json
+```
+
+The command checks local package files without contacting GitHub or the tailnet. It reports the manifest’s declared package version, source-file integrity, and the installed Tailscale binary version separately. An unknown source revision stays unknown. A matching manifest proves file consistency, not the identity of the publisher or readiness of the running service.
+
+Keep `source-manifest.json` with the four source files from the same reviewed revision. The new installer verifies that bundle and preserves the manifest in the installation. Never generate a new expected manifest from modified installed files to make a mismatch disappear. Existing v0.2/v0.3 installations without metadata report an unknown package version; the Tailscale version alone cannot identify the package.
+
+When staging an update or a rollback, keep the original manifest with its matching source files and restore them together. Do not copy a newer manifest over older code. Preserve node state, private keys, SSH identity and proxy settings. The manual update precautions below still apply; this command does not update or restart anything.
+
+JSON separates `package.declared_version`, `package.source_revision`, `package.integrity` and per-file results from `tailscale.version` and `tailscale.status`. Integrity is `match`, `mismatch` (modified or mixed files), `incomplete` (missing or unreadable files), or `unknown` (missing, invalid or unreadable metadata). `source_revision` is currently `null`; no commit is guessed. Exit code is `1` for mismatch/incomplete and `0` otherwise, so exit `0` alone does not prove a known version or available Tailscale binary. `doctor` reports unknown metadata as degraded and mismatch/incomplete as unhealthy.
+
+For maintainers: after intentional source changes, run `python3 scripts/source_manifest.py`, review the resulting diff, then run `python3 scripts/source_manifest.py --check`. CI runs the check without rewriting files. Regenerate only in the reviewed source checkout, not in an installed directory. A release must distribute the matching manifest alongside the four source assets; the existing v0.3.1 release does not contain it.
+
 <a id="development-helpers"></a>
 
 ## v0.3.1 helpers and optional application proxies

docs/usage.zh-CN.md

@@ -138,6 +138,27 @@ ssh -o StrictHostKeyChecking=yes -i /path/to/client_private_key 'agent@<tailscal
 
 本仓库没有 VM cron、systemd 服务或自动启动注册。尚未测试通过 Dots 自动化启动。VM 内的进程循环无法在该环境销毁后继续运行。请在新环境中显式启动安装，或通过单独验证过的平台执行机制启动。
 
+<a id="package-version"></a>
+
+## 软件包版本与文件校验（开发中）
+
+这是为 v0.4.0 开发的功能，上面的 v0.3.1 安装示例尚不包含它。发布新版本不会自动更新已有安装。
+
+```bash
+/workspace/.dots-tailscale/dots-ts version
+/workspace/.dots-tailscale/dots-ts version --json
+```
+
+命令只检查本地软件包文件，不连接 GitHub 或 tailnet。它分别显示清单声明的软件包版本、源文件的一致性和已安装的 Tailscale 程序版本。无法确定的源码修订版本会保留为未知。文件与清单一致，只能说明文件一致性，不能证明发布者身份，也不能证明正在运行的服务正常。
+
+请将同一已审核修订版本的四个源文件与 `source-manifest.json` 放在一起。新安装程序会校验这些文件，并将清单保存在安装目录中。不要用修改后的安装文件重新生成预期校验值来掩盖不一致。没有元数据的旧版 v0.2/v0.3 安装会显示软件包版本未知，不能仅凭 Tailscale 版本推断软件包版本。
+
+准备更新或回滚时，请把源文件与对应的原始清单作为一组保存并一起替换。不要只把新清单覆盖到旧代码上。保留节点状态、私钥、SSH 身份和代理设置。下方手动更新的注意事项仍然适用；此命令本身不会更新或重启服务。
+
+JSON 将 `package.declared_version`、`package.source_revision`、`package.integrity` 和逐文件结果，与 `tailscale.version`、`tailscale.status` 分开显示。一致性结果为 `match`、`mismatch`（文件被修改或版本混用）、`incomplete`（文件缺失或不可读）或 `unknown`（元数据缺失、无效或不可读）。目前 `source_revision` 为 `null`，不会猜测提交版本。mismatch/incomplete 的退出码为 `1`，其余为 `0`；因此，退出码 `0` 本身并不代表版本已知或 Tailscale 程序可用。`doctor` 将未知元数据标为 degraded，将文件不一致或不完整标为 unhealthy。
+
+维护时，在确认源码修改后运行 `python3 scripts/source_manifest.py`，检查生成的差异，再运行 `python3 scripts/source_manifest.py --check`。CI 只检查，不重写文件。请只在已审核的源码检出目录中生成清单，不要在安装目录中生成。发布时需要将匹配的清单与四个源文件一起提供；现有 v0.3.1 发布包不包含此清单。
+
 <a id="development-helpers"></a>
 
 ## v0.3.1 辅助工具与可选应用代理