@puddle-code/cli 0.5.0 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/CHANGELOG.md +9 -39
  2. package/README.md +10 -10
  3. package/dist/host-control.mjs +4063 -447
  4. package/dist/index.js +4700 -910
  5. package/dist/install-cli.sh +2 -2
  6. package/dist/install.sh +10 -6
  7. package/dist/public/assets/App-BV_yiDsr.js +19 -0
  8. package/dist/public/assets/{CompilationCommandForm-D7uBn2um.js → CompilationCommandForm-DXHvwQ8Y.js} +1 -1
  9. package/dist/public/assets/Dashboard-BF-uKZKM.js +1 -0
  10. package/dist/public/assets/DraftRecovery-B8Ld4_1b.js +1 -0
  11. package/dist/public/assets/EditorTabClose-CGYLU9GK.js +1 -0
  12. package/dist/public/assets/FileCloseScope-DoZ0oLf8.js +1 -0
  13. package/dist/public/assets/{FileEditorSettingsMenu-DnMJu5pC.js → FileEditorSettingsMenu-BbRHII96.js} +1 -1
  14. package/dist/public/assets/HuddlePane-LF3pjMQM.js +219 -0
  15. package/dist/public/assets/LazyTerminal-9xIh2FZq.js +2 -0
  16. package/dist/public/assets/ModelRefcount-CWfA9XXu.js +1 -0
  17. package/dist/public/assets/{NotebookWidget-DlpLANDa.js → NotebookWidget-BDdx0BOy.js} +1 -1
  18. package/dist/public/assets/PaneEditorBody-C1uu9cRG.js +284 -0
  19. package/dist/public/assets/PdfViewer-DLCPKybn.js +2 -0
  20. package/dist/public/assets/ReadOnlyDiff-C7ZSVRt-.js +2 -0
  21. package/dist/public/assets/{ReleaseNotesDialog-sQVKJ6dm.js → ReleaseNotesDialog-B9fRaZNN.js} +1 -1
  22. package/dist/public/assets/Ripple-BBMjOG3U.css +1 -0
  23. package/dist/public/assets/{Ripple-CLkhZZWa.js → Ripple-Dzg6tdOM.js} +1 -1
  24. package/dist/public/assets/SettingsDialog-BpB0nPgh.js +8 -0
  25. package/dist/public/assets/{Terminal-C3TQK74f.js → Terminal-4785ZuI8.js} +20 -20
  26. package/dist/public/assets/Workspace-DARXD6Je.js +20 -0
  27. package/dist/public/assets/{api--n1Ha6tG.js → api-CrP4jl9e.js} +1 -1
  28. package/dist/public/assets/auth-1SSLu56b.js +1 -0
  29. package/dist/public/assets/{buffer-logic-BAkSBQT7.js → buffer-logic-D9FvoilV.js} +1 -1
  30. package/dist/public/assets/buffer-store-OTFEYxTw.js +1 -0
  31. package/dist/public/assets/colour-picker-DZdAiaVI.js +1 -0
  32. package/dist/public/assets/content-state-CROLtMfN.js +1 -0
  33. package/dist/public/assets/{context-BRrQlmgI.js → context-NsaMZKAN.js} +1 -1
  34. package/dist/public/assets/disclosure-CpSwsC7J.js +1 -0
  35. package/dist/public/assets/drafts-CBbjQQbz.js +1 -0
  36. package/dist/public/assets/editor-context-T5zIHY3K.js +5 -0
  37. package/dist/public/assets/{editor-sync-C5CgYn_q.js → editor-sync-BOfDr2yY.js} +1 -1
  38. package/dist/public/assets/{errors-DWF9D4n6.js → errors-CviT-mvB.js} +1 -1
  39. package/dist/public/assets/expanding-content-ES1E2jvo.js +1 -0
  40. package/dist/public/assets/{file-editor-settings-1cj6VRxs.js → file-editor-settings-BXTs1F7S.js} +1 -1
  41. package/dist/public/assets/{file-links-BEPA2kg5.js → file-links-CgOYgoMC.js} +1 -1
  42. package/dist/public/assets/forward-link-qOyuWj08.js +1 -0
  43. package/dist/public/assets/hotkeys-nP8gYtE7.js +1 -0
  44. package/dist/public/assets/index-BB_BPKbu.css +2 -0
  45. package/dist/public/assets/index-TMXTPMjv.js +10 -0
  46. package/dist/public/assets/local-store-Dy1Cd8sn.js +276 -0
  47. package/dist/public/assets/{markdown-Cseepnv3.js → markdown-Dj7Cr7RL.js} +4 -4
  48. package/dist/public/assets/notification-delivery-DWXh5nfv.js +1 -0
  49. package/dist/public/assets/{preferences-Dy_61zsm.js → preferences-CvSHA-AA.js} +1 -1
  50. package/dist/public/assets/profile-icons-BI2xFWcB.js +1 -0
  51. package/dist/public/assets/{profile-store-CarO9MCP.js → profile-store-D4lZiXgL.js} +2 -2
  52. package/dist/public/assets/{project-actions-Zt9oqLe5.js → project-actions-Ck504AFM.js} +1 -1
  53. package/dist/public/assets/project-drag-BnkK15qk.js +1 -0
  54. package/dist/public/assets/{protocol-support-BUdL5Q-x.js → protocol-support-iXloAH0N.js} +1 -1
  55. package/dist/public/assets/queries-BSkHGZG8.js +1 -0
  56. package/dist/public/assets/queue-4USHmW_D.js +3 -0
  57. package/dist/public/assets/{render-rich-content-BULX1bwr.js → render-rich-content-fo4uQVWR.js} +1 -1
  58. package/dist/public/assets/save-BT7q_AMN.js +1 -0
  59. package/dist/public/assets/{scroll-restoration-Bl3jxJsC.js → scroll-restoration-C_ly1bKS.js} +1 -1
  60. package/dist/public/assets/selection-actions-2wBZeOyh.js +1 -0
  61. package/dist/public/assets/session-display-BUDNzNmg.js +1 -0
  62. package/dist/public/assets/session-order-b3nCJcCG.js +1 -0
  63. package/dist/public/assets/shield-check-CY69Ons-.js +1 -0
  64. package/dist/public/assets/source-anchor-map-BNxSa_bJ.js +1 -0
  65. package/dist/public/assets/square-terminal-CrlDquCd.js +1 -0
  66. package/dist/public/assets/state-CuUqRNo7.js +1 -0
  67. package/dist/public/assets/switch-CGrhQUXr.js +1 -0
  68. package/dist/public/assets/tooltip-Ek-eHPZu.js +1 -0
  69. package/dist/public/assets/trash-2-WYPJMQLN.js +1 -0
  70. package/dist/public/assets/{use-arrangement-ready-D18CpR8E.js → use-arrangement-ready-1vmV5np6.js} +1 -1
  71. package/dist/public/assets/use-desktop-state-CBTzsmlz.js +2 -0
  72. package/dist/public/assets/view-state-store-Dqk7M5ei.js +1 -0
  73. package/dist/public/assets/ws-CDXOuBYB.js +1 -0
  74. package/dist/public/assets/zoom-intent-vemBFIak.js +1 -0
  75. package/dist/public/index.html +8 -8
  76. package/dist/public/manifest.webmanifest +1 -1
  77. package/dist/public/notification-worker.js +1 -1
  78. package/dist/pudl.js +5816 -600
  79. package/package.json +2 -2
  80. package/dist/public/assets/App-ESs-lBsA.js +0 -49
  81. package/dist/public/assets/Dashboard-DWwOy6bQ.js +0 -1
  82. package/dist/public/assets/DraftRecovery-DO-ymSIW.js +0 -1
  83. package/dist/public/assets/EditorTabClose-DEizui0i.js +0 -1
  84. package/dist/public/assets/FileCloseScope-DKbSgHF2.js +0 -1
  85. package/dist/public/assets/LazyTerminal-B0GmOiTE.js +0 -2
  86. package/dist/public/assets/ModelRefcount-DBzR9UEq.js +0 -1
  87. package/dist/public/assets/PaneEditorBody-DRZ6NrJ1.js +0 -284
  88. package/dist/public/assets/PdfViewer-B3z9sh0x.js +0 -2
  89. package/dist/public/assets/Ripple-C8HPFMGB.css +0 -1
  90. package/dist/public/assets/SettingsDialog-DBUHpb9S.js +0 -8
  91. package/dist/public/assets/Workspace-D_NxUGYW.js +0 -20
  92. package/dist/public/assets/auth-eu0vmKkB.js +0 -1
  93. package/dist/public/assets/buffer-store-CBhXNRZm.js +0 -1
  94. package/dist/public/assets/content-state-BDt3NnGs.js +0 -1
  95. package/dist/public/assets/drafts-CCenbr5J.js +0 -1
  96. package/dist/public/assets/editor-links-qwyINDCv.js +0 -1
  97. package/dist/public/assets/expanding-content-BUkS1Qk4.js +0 -1
  98. package/dist/public/assets/forward-link-CcmVXHkx.js +0 -1
  99. package/dist/public/assets/index-Botodnry.js +0 -10
  100. package/dist/public/assets/index-rjm6DMrz.css +0 -2
  101. package/dist/public/assets/local-store-8IcyY3pd.js +0 -64
  102. package/dist/public/assets/notification-delivery-CWj1p0u-.js +0 -1
  103. package/dist/public/assets/project-drag-Bqy-V-45.js +0 -1
  104. package/dist/public/assets/queries-DnuokC1N.js +0 -1
  105. package/dist/public/assets/queue-BlrQxHDl.js +0 -3
  106. package/dist/public/assets/selection-actions-BSqrsD_7.js +0 -1
  107. package/dist/public/assets/session-order-CCDTBSiH.js +0 -1
  108. package/dist/public/assets/switch-BsUkvj8j.js +0 -1
  109. package/dist/public/assets/trash-2-DQeNROsF.js +0 -1
  110. package/dist/public/assets/use-desktop-state-Dw9EfOjg.js +0 -2
  111. package/dist/public/assets/view-state-store-CY9DI6-i.js +0 -1
  112. package/dist/public/assets/ws-DH0dKRnO.js +0 -1
package/CHANGELOG.md CHANGED
@@ -4,50 +4,20 @@ Archived release changelog. Governance lives in CLAUDE.md §"Changelog disciplin
4
4
 
5
5
  # Changelog
6
6
 
7
- ## [0.5.0] — 2026-11-08
7
+ ## [0.5.3] — 2026-11-09
8
8
 
9
- ### Cockpit
9
+ ### Frontend
10
10
 
11
- #### Added
11
+ #### Changed
12
12
 
13
- - Open projects in dedicated native windows, focus them through shared project navigation, and return their latest workspace after closing them even when no host window is open (application protocol 26.15; native OS acceptance remains in progress).
14
- - Drag a dedicated project's sidebar label back to its host, or use its return menu, preserving drafts and closing project ownership atomically (application protocol 26.16).
15
- - Open individual files and sessions in native pane windows from their existing context menus, and focus an existing detached view when reopening it (application protocol 26.9).
16
- - Open an entire pane in its own native window from its tab-strip context menu, preserving dirty text through an acknowledged handoff (application protocol 26.8).
17
- - Return detached panes to existing host/project windows through their context menu, preserving dirty text and view positions and retaining the source when late drafts remain (application protocol 26.11).
18
- - Connect detached pane dragging to the acknowledged return handoff, validate host/profile identity and place the pane in the destination's visible project (application protocol 26.12; native OS acceptance remains in progress).
19
- - Drag files, sessions and native tabs into existing pane windows through the same draft-preserving handoff, and keep filesystem/archive drag actions local to their source window (application protocol 26.13).
20
- - Highlight TeX and LaTeX commands, comments, environments, mathematics and verbatim text, with automatic file detection and a per-file language choice.
13
+ - Include the changes prepared for [v0.5.1](https://github.com/PerceptronV/puddle-code/blob/v0.5.3/docs/changelogs/CHANGELOG-v0.5.1.md) and [v0.5.2](https://github.com/PerceptronV/puddle-code/blob/v0.5.3/docs/changelogs/CHANGELOG-v0.5.2.md), whose release assets were not published.
21
14
 
22
- #### Changed
15
+ #### Fixed
16
+
17
+ - Verify Electron downloads against the official checksums in its locked npm package, avoiding repeated GitHub checksum-download timeouts during desktop packaging.
23
18
 
24
- - Review dirty files and untitled drafts when closing a native pane window, preserving cancellation and app-quit recovery and checking retained drafts again before closure (application protocol 26.22).
25
- - Show only the project name in workspace window titles and the active file or session name in detached pane titles.
26
- - Coordinate native notification sounds/delivery and update offers across windows, retain notifications when their original window closes, and route clicks to the correct profile or detached session (application protocol 26.21).
27
- - Save, duplicate and load native window arrangements through the host Layouts popover, including project saves from the dashboard; preserve mounted editors when saving and observe uncertain loads without redispatch.
28
- - Coordinate native arrangement application with scoped window matching, draft-preserving plans, atomic ownership and cancellation recovery; retain each restored window's layout mode without changing client preferences (application protocol 26.20; native OS acceptance remains in progress).
29
- - Stage native layout participants through the reused workspace/dashboard, verify mounted revisions and preserve drafts on cancellation (application protocol 26.19).
30
- - Coordinate native layout capture across window checkpoints and prepare atomic multi-window recovery transactions with draft retention (application protocol 26.18).
31
- - Prepare named native window layouts with portable arrangement storage, scoped capture projections and a single-tree browser fallback (application protocol 26.17).
32
- - Support typing through Ripple when its divider covers the live input, reusing native keyboard, paste and IME handling with anchored cells and a visible caret. Preserve the default display-only split and native composer.
33
-
34
- - Prepare project-window handoffs with durable return records and shared destination planning; subsequent controls use the same ownership flow (application protocol 26.14).
35
- - Refresh the Puddle logo across the favicon, in-app branding, web app and notification icons, and macOS/Linux desktop icons.
36
- - Separate native window lifetime from host connections and retain revisioned desktop working sets and acknowledged transfer records (application protocol 26.7).
37
- - Flush desktop working sets and dirty drafts before native close or Command-Q, and cancel closure when a renderer cannot confirm its checkpoint.
38
- - Preserve editor selections when detaching from project-based layouts by translating their saved view-state scope.
39
- - Save native window drafts before reload or host refresh, serialise navigation per host, and let Command-Q wait for pending navigation (application protocol 26.10).
19
+ ### Daemon
40
20
 
41
21
  #### Fixed
42
22
 
43
- - Recover a native destination's lost acceptance reply by observing the committed transfer, keeping returned projects editable after their source window closes.
44
- - Allow docking again after a destination renderer crashes and reloads, clearing its stale restoration flag while preserving draft rollback.
45
- - Keep Monaco hover services alive when source/preview panes detach or dock, preventing disposed diff-editor services from crashing sibling editors.
46
- - Preserve shared dirty text and draft persistence when closing a duplicate file view; ask to discard only when its last view closes.
47
- - Reuse draft review when closing native panes with missing projects or profiles, expose orphaned drafts without remounting editors, and preserve independent cached edits when discarding recovery copies.
48
- - Wait for pending untitled-draft saves before approved deletion, prevent discard dialogues from reactivating closed tabs, and keep the last explicitly closed native window out of restart recovery.
49
- - Use the file tab's discard dialogue for keyboard closure too, retaining unsaved text on cancellation and preventing closure before the lazy dirty-file check loads.
50
- - Cancel pending local draft writes after an approved discard so closing the editor cannot restore the discarded text on reopen.
51
- - Keep unavailable native tabs and expose retained draft text for copying or downloading when a file, session or project disappears; preserve discard confirmation and restore editing after retry.
52
- - Keep project and pane window titles identifiable when unrelated host sessions change status, and restore the current host title on leaving the workspace.
53
- - Preserve the active editor on native window reload when the URL retains a previous session binding.
23
+ - Make private runtime fixtures independent of the host umask, wait for uncontended pre-launch admission, and end the owner first when testing crash recovery.
package/README.md CHANGED
@@ -13,8 +13,8 @@ Puddle manages parallel agents on local and SSH hosts, isolates work in dedicate
13
13
 
14
14
  <p align="center">
15
15
  <picture>
16
- <source media="(prefers-color-scheme: dark)" srcset="docs/assets/cockpit-dark.png">
17
- <img src="docs/assets/cockpit-light.png" alt="The Puddle desktop app: a live Claude Code session split beside the rendered README, with the file explorer on the left and parallel agent sessions on their own branches and accounts in the sidebar" width="920">
16
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/frontend-dark.png">
17
+ <img src="docs/assets/frontend-light.png" alt="The Puddle desktop app: a live Claude Code session split beside the rendered README, with the file explorer on the left and parallel agent sessions on their own branches and accounts in the sidebar" width="920">
18
18
  </picture>
19
19
  </p>
20
20
 
@@ -76,7 +76,7 @@ puddle launch
76
76
  This installs the Puddle daemon under `~/.puddle` and serves the GUI at `http://localhost:7433`.
77
77
 
78
78
  Ctrl-C normally closes only the GUI while independently supervised runtimes keep running.
79
- Some SSH hosts require a cockpit-held daemon. Closing that cockpit stops the daemon and
79
+ Some SSH hosts require a frontend-held daemon. Closing that frontend stops the daemon and
80
80
  detaches its independent owners; host policy may retain or reap those host-session runtimes.
81
81
  Reconnection adopts survivors and restores interrupted sessions according to the host's
82
82
  auto-resume setting. These limited hosts do not support managed updates without a usable
@@ -104,7 +104,7 @@ Runtime install/upgrade requires a running daemon with host-update support (appl
104
104
 
105
105
  **Desktop app (optional):**
106
106
 
107
- The same cockpit also ships as a standalone desktop app — identical UI and engine, plus a File → "Connect to SSH Host…" menu for remote hosts. Install it with `puddle install desktop` (macOS arm64 or Linux x64/arm64). Once installed, it runs independently of the CLI.
107
+ The same frontend also ships as a standalone desktop app — identical UI and engine, plus a File → "Connect to SSH Host…" menu for remote hosts. Install it with `puddle install desktop` (macOS arm64 or Linux x64/arm64). Once installed, it runs independently of the CLI.
108
108
 
109
109
  An installed Puddle CLI manages the desktop app directly: quit Puddle, then `puddle install desktop`, `puddle upgrade desktop`, or `puddle remove desktop`. On macOS a fresh install goes to `/Applications` when writable, otherwise `~/Applications`; on Linux `install desktop` asks where to put the AppImage (default `~/puddle`) and opens the folder — later updates happen from inside the app.
110
110
 
@@ -115,7 +115,7 @@ auth prompts unless you use a key).
115
115
 
116
116
  ## How it works
117
117
 
118
- - **Puddle separates host management from live execution.** First connection installs a missing daemon on a supported local or SSH host. In the 0.4.0 architecture, `puddled` manages worktrees and application state, while one independent `puddler` per runtime owns agent and shell PTYs and provider sidecars. Supervised owners survive daemon replacement and cockpit disconnects. After machine reboot, saved conversations can resume according to host settings; live process state does not survive reboot. Hosts without a usable service manager retain the limited host-session fallback described above.
118
+ - **Puddle separates host management from live execution.** First connection installs a missing daemon on a supported local or SSH host. In the 0.4.0 architecture, `puddled` manages worktrees and application state, while one independent `puddler` per runtime owns agent and shell PTYs and provider sidecars. Supervised owners survive daemon replacement and frontend disconnects. After machine reboot, saved conversations can resume according to host settings; live process state does not survive reboot. Hosts without a usable service manager retain the limited host-session fallback described above.
119
119
  - **Puddle orchestrates parallel isolated agents** each working in a unique git worktree and branch. You can choose the branch and worktree during session creation.
120
120
  - **Puddle's lightweight GUI** allows you to track agent progress, session usage, and active worktrees.
121
121
  - **Puddle's philosophy is that any good developer must stay grounded in their code.** Puddle natively integrates live terminals, file editing in Monaco, git commit grahps, diff views, and opens worktrees in your favourite IDE.
@@ -137,13 +137,13 @@ auth prompts unless you use a key).
137
137
  └───────────────────────────────────┘
138
138
  ```
139
139
 
140
- The CLI serves the UI at a stable local origin and reverse-proxies the API to the daemon, directly in local mode, through the tunnel in SSH mode. The daemon is headless and host-agnostic on `127.0.0.1:7434`. UI updates ship with the CLI. Compatible cockpit and daemon releases may differ; the launcher requires approval when an older application protocol is incompatible. Explicit daemon/runtime updates also use the CLI or supporting cockpit Host settings. Review distinguishes unaffected independent runtimes from work requiring interruption; first upgrades from daemon-owned sessions report their interruption count. Declining leaves the daemon running. `--no-upgrade` refuses before prompting, and non-interactive launches require an explicit `puddle upgrade daemon [user@host]` first. Short-lived host connection leases, separate browser authorisation and exact cockpit Host/Origin checks guard local access. Launch invitations are single-use; browser login survives cockpit restarts, while forwarded applications use a separate loopback origin. After upgrading from the old token flow, run `puddle launch` once to authorise existing tabs.
140
+ The CLI serves the UI at a stable local origin and reverse-proxies the API to the daemon, directly in local mode, through the tunnel in SSH mode. The daemon is headless and host-agnostic on `127.0.0.1:7434`. UI updates ship with the CLI. Compatible frontend and daemon releases may differ; the launcher requires approval when an older application protocol is incompatible. Explicit daemon/runtime updates also use the CLI or supporting frontend Host settings. Review distinguishes unaffected independent runtimes from work requiring interruption; first upgrades from daemon-owned sessions report their interruption count. Declining leaves the daemon running. `--no-upgrade` refuses before prompting, and non-interactive launches require an explicit `puddle upgrade daemon [user@host]` first. Short-lived host connection leases, separate browser authorisation and exact frontend Host/Origin checks guard local access. Launch invitations are single-use; browser login survives frontend restarts, while forwarded applications use a separate loopback origin. After upgrading from the old token flow, run `puddle launch` once to authorise existing tabs.
141
141
 
142
142
  Everything lives under `~/.puddle` on the host, installed without sudo — and `puddle remove daemon` takes it apart again.
143
143
 
144
144
  ## Development & teardown
145
145
 
146
- **UI preview without a daemon.** Run `pnpm --filter @puddle/web dev:preview` and open <http://localhost:5174>. The real cockpit opens a sample project with coloured file icons, expandable folders and editable sample files. Appearance settings work normally. Sample saves last until reload; terminals, agents and host operations are unavailable. This mode uses browser-only fixtures, has no host gateway and is excluded from production builds. The sample `examples/` folder includes a notebook and PDF; Search, Changes, Worktrees and ended sample sessions exercise the navigator layouts. With the preview running, `pnpm --filter @puddle/web test:preview` checks the sample screens, repeated editor resizing, whole-pane dragging and inline diff close controls in Chromium. Use `pnpm --filter @puddle/web dev` to work against a compatible local daemon instead.
146
+ **UI preview without a daemon.** Run `pnpm --filter @puddle/web dev:preview` and open <http://localhost:5174>. The real frontend opens a sample project with coloured file icons, expandable folders and editable sample files. Appearance settings work normally. Sample saves last until reload; terminals, agents and host operations are unavailable. This mode uses browser-only fixtures, has no host gateway and is excluded from production builds. The sample `examples/` folder includes a notebook and PDF; Search, Changes, Worktrees and ended sample sessions exercise the navigator layouts. With the preview running, `pnpm --filter @puddle/web test:preview` checks the sample screens, repeated editor resizing, whole-pane dragging and inline diff close controls in Chromium. Use `pnpm --filter @puddle/web dev` to work against a compatible local daemon instead.
147
147
 
148
148
  **One daemon, many clients.** There is a single local daemon per machine, living under `~/.puddle` and run by one supervised service (launchd's `dev.puddle.puddled` on macOS, systemd's `puddled` on Linux). The global `puddle` and a repo-run `node packages/cli/dist/index.js` are **both just clients** that talk to — and, when needed, install — that same daemon. Multiple clients can share that daemon; there is no automatically separate "dev daemon" alongside a "production daemon".
149
149
 
@@ -155,11 +155,11 @@ node packages/cli/dist/index.js upgrade daemon@X.Y.Z --tarball dist-release/pudd
155
155
  node packages/cli/dist/index.js launch --foreground
156
156
  ```
157
157
 
158
- Replace `X.Y.Z`, `PLATFORM` and `ARCH` with the version and target printed by `build:tarball`; keep the generated `.sha256` file beside the archive. Add `user@host` after the component for an SSH target. A modern stopped installation starts its selected service before an explicit upgrade; `launch --tarball` alone does not replace that selected build. A compatible running daemon also ignores the launch tarball. To select the same archive for future runtime launches, use `upgrade runtime@X.Y.Z --tarball …`; existing owners remain pinned until explicitly restarted. First installation and approved legacy transitions still use the embedded bootstrap. Both clients share the host's daemon and cockpit registry. Never launch the daemon from inside a coding-agent shell: it inherits the agent's environment and can break conversation resume; use a plain terminal.
158
+ Replace `X.Y.Z`, `PLATFORM` and `ARCH` with the version and target printed by `build:tarball`; keep the generated `.sha256` file beside the archive. Add `user@host` after the component for an SSH target. A modern stopped installation starts its selected service before an explicit upgrade; `launch --tarball` alone does not replace that selected build. A compatible running daemon also ignores the launch tarball. To select the same archive for future runtime launches, use `upgrade runtime@X.Y.Z --tarball …`; existing owners remain pinned until explicitly restarted. First installation and approved legacy transitions still use the embedded bootstrap. Both clients share the host's daemon and frontend registry. Never launch the daemon from inside a coding-agent shell: it inherits the agent's environment and can break conversation resume; use a plain terminal.
159
159
 
160
- **Kill.** `puddle kill --all` (or Ctrl-C in a `--foreground` run) normally stops the local cockpit
160
+ **Kill.** `puddle kill --all` (or Ctrl-C in a `--foreground` run) normally stops the local frontend
161
161
  UI only; a supervised daemon and its sessions keep running. When launch reported that it is keeping
162
- the daemon attached over SSH, killing that cockpit stops the daemon. Host-session owners may
162
+ the daemon attached over SSH, killing that frontend stops the daemon. Host-session owners may
163
163
  survive or be reaped by host policy; the next launch adopts survivors and reconciles ended
164
164
  owners according to the host auto-resume setting.
165
165
  A supervised daemon is auto-restarting