twin-update 0.2.0__tar.gz

twin_update-0.2.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.2.0 (2026-10-09)
+
+First public release.
+
+* Fixed: `doctor`, `holds` and `unhold` printed nothing without `--json`
+  (also when stdout is not a terminal). Every command now prints plain text;
+  anything without a formatter falls back to the JSON report.
+* Machines can use the same user name: the config's `machine_id_sha256`
+  decides which table is "this machine".
+* Machine labels are fully user-defined; docs and examples use generic labels.
+* README: security model summary and generic Tailscale policy guidance.
+* Packaging metadata for PyPI (classifiers, project URLs).
+
+## 0.1.0 (2026-10-09, not published)
+
+First version.
+
+* `status`, `run`, `rollback`, `holds`, `unhold`, `doctor`, `local --serve`.
+* Two machines, one run: identity check, lock files held, sudo asked once,
+  same pinned version on both or skipped on both.
+* Graceful close only (pidfd SIGTERM); a close timeout aborts on both machines
+  before any update, and the apps it closed are reopened.
+* Verified rollback copy captured before every update; exactly one kept per app,
+  older ones pruned after verification plus a grace period.
+* Holds not set by Twin Update are cleared unless `keep_holds` lists them.
+* Launch smoke test, per-run JSON report (0600, labels only), desktop notification.
+* Single-file zipapp build (compressed); standard library only.
+* Rollback copies of vendor debs without an md5sums member are verified by
+  hashing the deb's files against dpkg's record; a mismatch is refused, also
+  in a dry run.
+* Notification falls back to `gdbus` when `notify-send` is not installed and
+  soft-fails when neither is; `doctor` reports `notify_tool`.

twin_update-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

twin_update-0.2.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md CHANGELOG.md SECURITY.md LICENSE config.example.toml
+recursive-include tests *.py
+include tools/build_zipapp.py

twin_update-0.2.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: twin-update
+Version: 0.2.0
+Summary: Close, update and verify the same apt-packaged desktop apps on two Linux machines in one run, with a verified one-command rollback.
+Author: Dragon Lady
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Dragon-Lady/twin-update
+Project-URL: Source, https://github.com/Dragon-Lady/twin-update
+Project-URL: Issues, https://github.com/Dragon-Lady/twin-update/issues
+Project-URL: Changelog, https://github.com/Dragon-Lady/twin-update/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/Dragon-Lady/twin-update/security/policy
+Keywords: apt,updates,rollback,desktop,linux,tailscale
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Twin Update
+
+Update the same desktop apps on two Linux machines in **one run**, keep a
+verified rollback copy of what was installed, and roll back with **one command**.
+
+It targets Debian/Ubuntu-family desktops (tested on Ubuntu 24.04-based
+systems with Python 3.12; needs Python 3.11+, systemd user sessions and apt)
+and apps installed as **apt packages from their vendor repos**. Built-in
+entries: Cursor (`cursor`), ChatGPT desktop (`chatgpt`) and Grok Bot desktop
+(`grok-bot`). Other apt-packaged apps can be added in the config. Snaps,
+Flatpaks, AppImages and CLIs are out of scope.
+
+Machine labels are whatever you name them in the config; the examples below
+use `desktop-a` and `laptop-b`.
+
+## Security model, in short
+
+* **Two machines you control, one trusted link.** The machine you start the
+  run on reaches the other over `ssh` (BatchMode, host keys checked):
+  Tailscale SSH or an ordinary ssh key. Without that link only
+  `--local-only --dry-run` works.
+* **sudo is asked once per run** and checked on both machines. The password
+  goes only to `sudo -S` on stdin (over the run's ssh session for the other
+  machine); never argv, environment, files, logs or reports. See
+  [SECURITY.md](SECURITY.md).
+* **apt only.** Root runs only `apt-get update`, `apt-get install` of a pinned
+  version or of a stored, sha256-checked `.deb`, and `apt-mark hold/unhold`.
+  Each machine installs from its own configured apt sources.
+* **Graceful closes only.** SIGTERM, never SIGKILL. If an app does not close
+  in time, the run **aborts on both machines before anything is updated**.
+* **Rollback copy before every update**, verified against what dpkg installed;
+  no verified copy on either machine means the app is skipped on both.
+* **Nothing resident.** No daemon, timer or listener; apps close only inside a
+  run you start.
+* It restores program files, not app data (see below).
+
+## What a run does
+
+```
+twin-update run [--apps cursor,chatgpt] [--dry-run]
+```
+
+1. **Preflight on both machines**: identity (`whoami`, optional machine-id) must
+   match the config; apt/dpkg must be idle; every `lock_paths` file is locked
+   for the whole run, so a sync or backup job cannot run during the update.
+   Asks for the sudo password **once** and checks it on both machines, then
+   `apt-get update` on both.
+2. **Plan**: an app is updated only if both machines have it installed, are
+   offered the **same** candidate version, and no kept hold blocks it. Otherwise
+   it is skipped on both, with the reason. The exact version is pinned.
+3. **Rollback copy first**: the installed `.deb` is stored in
+   `~/.local/share/twin-update/rollback/<app>/<version>/` with a sha256, taken
+   from the apt cache, `apt-get download <pkg>=<installed>`, or a matching local
+   `.deb`. It is checked against dpkg's md5sums of the installed build (for
+   vendor debs without an md5sums member, the deb's files are hashed in a
+   stream and compared). A mismatch is refused. No copy on either machine =
+   the app is skipped on both.
+4. **Holds**: holds on these apps that Twin Update did not set are cleared (one
+   report line each) unless `keep_holds` lists them. Holds on other packages
+   are only reported.
+5. **Graceful close on both**: SIGTERM (via pidfd) to the main processes of the
+   app's process tree, found by executable path and the package's file list.
+   No force-kill. If anything is still running after `close_s`, the run
+   **aborts on both machines before any update**, names the app and process,
+   and reopens what it closed.
+6. **Update** each machine from its own repo: `apt-get install --only-upgrade
+   <pkg>=<version>`. Nothing is copied between machines.
+7. **Verify**: dpkg version, `dpkg -V`, and a launch smoke test in the graphical
+   session (`systemd-run --user`): stays up `smoke_s` seconds, no crash in the
+   journal, closes gracefully. On failure you are offered a rollback.
+8. **Reopen** only the apps that were open before.
+9. **Prune**: exactly one rollback copy per app is kept (the version before the
+   latest update). Older copies are removed only after the new version passed
+   its checks **and** a grace period (7 days or 2 good launches).
+10. **Report**: `~/.local/state/twin-update/runs/<ts>-run.json` (0600, machine
+    labels only) on both machines, plus a desktop notification such as
+    `Cursor laptop-b 2.4.1→2.5.0 ✓` (via `notify-send`, or `gdbus`
+    when `notify-send` is not installed).
+
+Apps are only ever closed inside a run you start. There is no daemon, timer,
+watcher or listener; the ssh session to the other machine exists only for the run.
+The run moves itself into its own `systemd-run --user --scope`, so closing the
+app whose terminal launched it does not stop it.
+
+## Other commands
+
+```
+twin-update status [--local-only]          # per machine/app: installed, candidate, running, rollback copy, hold
+twin-update rollback <app> [--machine <label>|both] [--dry-run] [--no-hold]
+twin-update holds
+twin-update unhold <app> [--machine ...] [--dry-run]
+twin-update doctor                         # identity, sudo group, apt idle, locks, session, ssh
+twin-update local --serve                  # per-machine engine; the peer runs this over ssh
+```
+
+`rollback` checks the stored copy's sha256, closes the app gracefully, installs
+it with `apt-get install --allow-downgrades ./<deb>`, sets `apt-mark hold`
+(recorded as Twin Update's own hold; the next deliberate `run` releases it),
+verifies, and reopens the app if it was open.
+
+A rollback restores **program files, not app data**. If a new version migrated
+its settings or databases, keep your own data backups. Twin Update never opens,
+copies or modifies app databases.
+
+## Install (each machine)
+
+```
+pipx install twin-update          # or: uv tool install twin-update
+```
+
+or the single-file zipapp from a release:
+
+```
+install -D -m 0755 twin-update.pyz ~/.local/bin/twin-update
+```
+
+Install it at the same path on both machines (`remote_command` in the config
+points to it). Then create `~/.config/twin-update/config.toml` (mode 0600)
+from `config.example.toml`. The same file works on both machines. Check with
+`twin-update doctor`, then `twin-update run --dry-run`.
+
+### Transport
+
+The machine you run on reaches the other with plain `ssh` (BatchMode, host
+keys checked, no password prompts). The remote side runs
+`twin-update local --serve` for the length of the run. Two options:
+
+**Tailscale SSH.** On each machine that should accept runs:
+`sudo tailscale set --ssh`. "Shields up" blocks incoming connections, Tailscale
+SSH included, so it must be off on those machines; let the policy do the
+limiting instead. Example policy fragment with tags (merge it into your
+policy; tagging a device makes it tag-owned rather than user-owned):
+
+```json
+{
+  "tagOwners": {
+    "tag:twin-a": ["autogroup:admin"],
+    "tag:twin-b": ["autogroup:admin"]
+  },
+  "grants": [
+    { "src": ["tag:twin-a"], "dst": ["tag:twin-b"], "ip": ["tcp:22"] },
+    { "src": ["tag:twin-b"], "dst": ["tag:twin-a"], "ip": ["tcp:22"] }
+  ],
+  "ssh": [
+    { "action": "accept", "src": ["tag:twin-a"], "dst": ["tag:twin-b"], "users": ["alice"] },
+    { "action": "accept", "src": ["tag:twin-b"], "dst": ["tag:twin-a"], "users": ["alice"] }
+  ]
+}
+```
+
+Use `"action": "accept"`: `"check"` needs an interactive browser login and a
+BatchMode run cannot answer it. If your policy still has an allow-all rule,
+it also lets everything else in the tailnet reach these machines; narrow it.
+Keep only the direction you need if you always start runs on the same machine.
+
+**Plain ssh key.** A dedicated key without a passphrase prompt (or one held by
+your agent) in the other machine's `authorized_keys`, ideally limited with
+`from="<the other machine's address>"`, and its host key already in
+`known_hosts`.
+
+## Development
+
+```
+PYTHONPATH=src:tests python3 -m unittest discover -s tests
+python3 tools/build_zipapp.py        # -> dist/twin-update.pyz
+```
+
+Standard library only. Exit codes: 0 ok / dry-run, 1 failed, 2 usage or config,
+3 aborted (nothing changed).
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

twin_update-0.2.0/README.md

@@ -0,0 +1,173 @@
+# Twin Update
+
+Update the same desktop apps on two Linux machines in **one run**, keep a
+verified rollback copy of what was installed, and roll back with **one command**.
+
+It targets Debian/Ubuntu-family desktops (tested on Ubuntu 24.04-based
+systems with Python 3.12; needs Python 3.11+, systemd user sessions and apt)
+and apps installed as **apt packages from their vendor repos**. Built-in
+entries: Cursor (`cursor`), ChatGPT desktop (`chatgpt`) and Grok Bot desktop
+(`grok-bot`). Other apt-packaged apps can be added in the config. Snaps,
+Flatpaks, AppImages and CLIs are out of scope.
+
+Machine labels are whatever you name them in the config; the examples below
+use `desktop-a` and `laptop-b`.
+
+## Security model, in short
+
+* **Two machines you control, one trusted link.** The machine you start the
+  run on reaches the other over `ssh` (BatchMode, host keys checked):
+  Tailscale SSH or an ordinary ssh key. Without that link only
+  `--local-only --dry-run` works.
+* **sudo is asked once per run** and checked on both machines. The password
+  goes only to `sudo -S` on stdin (over the run's ssh session for the other
+  machine); never argv, environment, files, logs or reports. See
+  [SECURITY.md](SECURITY.md).
+* **apt only.** Root runs only `apt-get update`, `apt-get install` of a pinned
+  version or of a stored, sha256-checked `.deb`, and `apt-mark hold/unhold`.
+  Each machine installs from its own configured apt sources.
+* **Graceful closes only.** SIGTERM, never SIGKILL. If an app does not close
+  in time, the run **aborts on both machines before anything is updated**.
+* **Rollback copy before every update**, verified against what dpkg installed;
+  no verified copy on either machine means the app is skipped on both.
+* **Nothing resident.** No daemon, timer or listener; apps close only inside a
+  run you start.
+* It restores program files, not app data (see below).
+
+## What a run does
+
+```
+twin-update run [--apps cursor,chatgpt] [--dry-run]
+```
+
+1. **Preflight on both machines**: identity (`whoami`, optional machine-id) must
+   match the config; apt/dpkg must be idle; every `lock_paths` file is locked
+   for the whole run, so a sync or backup job cannot run during the update.
+   Asks for the sudo password **once** and checks it on both machines, then
+   `apt-get update` on both.
+2. **Plan**: an app is updated only if both machines have it installed, are
+   offered the **same** candidate version, and no kept hold blocks it. Otherwise
+   it is skipped on both, with the reason. The exact version is pinned.
+3. **Rollback copy first**: the installed `.deb` is stored in
+   `~/.local/share/twin-update/rollback/<app>/<version>/` with a sha256, taken
+   from the apt cache, `apt-get download <pkg>=<installed>`, or a matching local
+   `.deb`. It is checked against dpkg's md5sums of the installed build (for
+   vendor debs without an md5sums member, the deb's files are hashed in a
+   stream and compared). A mismatch is refused. No copy on either machine =
+   the app is skipped on both.
+4. **Holds**: holds on these apps that Twin Update did not set are cleared (one
+   report line each) unless `keep_holds` lists them. Holds on other packages
+   are only reported.
+5. **Graceful close on both**: SIGTERM (via pidfd) to the main processes of the
+   app's process tree, found by executable path and the package's file list.
+   No force-kill. If anything is still running after `close_s`, the run
+   **aborts on both machines before any update**, names the app and process,
+   and reopens what it closed.
+6. **Update** each machine from its own repo: `apt-get install --only-upgrade
+   <pkg>=<version>`. Nothing is copied between machines.
+7. **Verify**: dpkg version, `dpkg -V`, and a launch smoke test in the graphical
+   session (`systemd-run --user`): stays up `smoke_s` seconds, no crash in the
+   journal, closes gracefully. On failure you are offered a rollback.
+8. **Reopen** only the apps that were open before.
+9. **Prune**: exactly one rollback copy per app is kept (the version before the
+   latest update). Older copies are removed only after the new version passed
+   its checks **and** a grace period (7 days or 2 good launches).
+10. **Report**: `~/.local/state/twin-update/runs/<ts>-run.json` (0600, machine
+    labels only) on both machines, plus a desktop notification such as
+    `Cursor laptop-b 2.4.1→2.5.0 ✓` (via `notify-send`, or `gdbus`
+    when `notify-send` is not installed).
+
+Apps are only ever closed inside a run you start. There is no daemon, timer,
+watcher or listener; the ssh session to the other machine exists only for the run.
+The run moves itself into its own `systemd-run --user --scope`, so closing the
+app whose terminal launched it does not stop it.
+
+## Other commands
+
+```
+twin-update status [--local-only]          # per machine/app: installed, candidate, running, rollback copy, hold
+twin-update rollback <app> [--machine <label>|both] [--dry-run] [--no-hold]
+twin-update holds
+twin-update unhold <app> [--machine ...] [--dry-run]
+twin-update doctor                         # identity, sudo group, apt idle, locks, session, ssh
+twin-update local --serve                  # per-machine engine; the peer runs this over ssh
+```
+
+`rollback` checks the stored copy's sha256, closes the app gracefully, installs
+it with `apt-get install --allow-downgrades ./<deb>`, sets `apt-mark hold`
+(recorded as Twin Update's own hold; the next deliberate `run` releases it),
+verifies, and reopens the app if it was open.
+
+A rollback restores **program files, not app data**. If a new version migrated
+its settings or databases, keep your own data backups. Twin Update never opens,
+copies or modifies app databases.
+
+## Install (each machine)
+
+```
+pipx install twin-update          # or: uv tool install twin-update
+```
+
+or the single-file zipapp from a release:
+
+```
+install -D -m 0755 twin-update.pyz ~/.local/bin/twin-update
+```
+
+Install it at the same path on both machines (`remote_command` in the config
+points to it). Then create `~/.config/twin-update/config.toml` (mode 0600)
+from `config.example.toml`. The same file works on both machines. Check with
+`twin-update doctor`, then `twin-update run --dry-run`.
+
+### Transport
+
+The machine you run on reaches the other with plain `ssh` (BatchMode, host
+keys checked, no password prompts). The remote side runs
+`twin-update local --serve` for the length of the run. Two options:
+
+**Tailscale SSH.** On each machine that should accept runs:
+`sudo tailscale set --ssh`. "Shields up" blocks incoming connections, Tailscale
+SSH included, so it must be off on those machines; let the policy do the
+limiting instead. Example policy fragment with tags (merge it into your
+policy; tagging a device makes it tag-owned rather than user-owned):
+
+```json
+{
+  "tagOwners": {
+    "tag:twin-a": ["autogroup:admin"],
+    "tag:twin-b": ["autogroup:admin"]
+  },
+  "grants": [
+    { "src": ["tag:twin-a"], "dst": ["tag:twin-b"], "ip": ["tcp:22"] },
+    { "src": ["tag:twin-b"], "dst": ["tag:twin-a"], "ip": ["tcp:22"] }
+  ],
+  "ssh": [
+    { "action": "accept", "src": ["tag:twin-a"], "dst": ["tag:twin-b"], "users": ["alice"] },
+    { "action": "accept", "src": ["tag:twin-b"], "dst": ["tag:twin-a"], "users": ["alice"] }
+  ]
+}
+```
+
+Use `"action": "accept"`: `"check"` needs an interactive browser login and a
+BatchMode run cannot answer it. If your policy still has an allow-all rule,
+it also lets everything else in the tailnet reach these machines; narrow it.
+Keep only the direction you need if you always start runs on the same machine.
+
+**Plain ssh key.** A dedicated key without a passphrase prompt (or one held by
+your agent) in the other machine's `authorized_keys`, ideally limited with
+`from="<the other machine's address>"`, and its host key already in
+`known_hosts`.
+
+## Development
+
+```
+PYTHONPATH=src:tests python3 -m unittest discover -s tests
+python3 tools/build_zipapp.py        # -> dist/twin-update.pyz
+```
+
+Standard library only. Exit codes: 0 ok / dry-run, 1 failed, 2 usage or config,
+3 aborted (nothing changed).
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

twin_update-0.2.0/SECURITY.md

@@ -0,0 +1,51 @@
+# Security notes
+
+## sudo password
+
+* Asked **once** per run with `getpass` (no echo).
+* Locally it is written only to the stdin of `sudo -k -S -p '' -- <command>`.
+  `-k` makes sudo ignore cached credentials so it always consumes exactly that
+  line; nothing left over reaches the command's stdin.
+* For the other machine it travels **inside the run's ssh session** as one JSON
+  line on the remote `twin-update local --serve` stdin, and is used the same way
+  there.
+* It is never placed in argv, environment variables, files, reports or logs.
+  The serve loop never echoes request arguments. Both engines keep it in a
+  `bytearray` and overwrite it with zeros when the run ends (Python may still
+  hold transient copies until garbage collection; that is a known limit).
+* The test suite asserts that the password appears in no argv, env, log line,
+  report or file, and only on sudo's stdin.
+
+## What runs as root
+
+Only: `true` (password check), `apt-get update`, `apt-get install
+--only-upgrade <pkg>=<version>`, `apt-get install --allow-downgrades <stored
+deb>` (after its sha256 check), `apt-mark hold|unhold <pkg>`.
+
+## Processes
+
+Apps are closed only with SIGTERM through a pidfd after re-checking the
+process start time (no PID-reuse races). Twin Update never sends SIGKILL; a
+close timeout aborts the run on both machines before any update.
+
+## Network
+
+No listener, daemon or timer. The ssh session (BatchMode, host keys checked)
+exists only while a command runs.
+
+## Trust boundaries
+
+* Both machines must be yours. The sudo password typed on one machine is used
+  on the other, so the other machine and the ssh link to it must be trusted
+  as much as the one you type on.
+* Anyone who can already ssh in as your user on either machine could run
+  Twin Update there, but still needs the sudo password for every root step.
+* Apps come from each machine's own apt sources and their signing keys; Twin
+  Update does not add repositories or keys and does not copy packages between
+  machines.
+* Rollback copies are stored per user (0700 directories, 0600 files) with a
+  sha256 that is checked before any rollback install.
+
+## Reporting
+
+Please report issues privately through the repository's security advisories.