@puddle-code/cli 0.2.4 → 0.2.7

package/CHANGELOG.md

@@ -1,25 +1,15 @@
 <!--
-Rolling changelog for the NEXT release. Governance lives in CLAUDE.md §"Changelog discipline".
-On publish: retitle [Unreleased] to [X.Y.Z] — date, archive a copy to
-docs/changelogs/CHANGELOG-vX.Y.Z.md, then reset this file to this template.
-Past releases: see docs/changelogs/.
+Archived release changelog. Governance lives in CLAUDE.md §"Changelog discipline".
 -->
 
 # Changelog
 
-## [0.2.4] — 2026-09-22
-
-### Added
-
-- Add Paste beside Copy in mobile terminal long-press controls, including empty inputs, preserving terminal paste handling without adding Enter.
-- Raise mobile terminal image uploads to 4 MiB with progress and cancellation, preserve smaller originals and recompress larger photos while retaining ordinary remote request limits (daemon/cockpit protocol 21.2; encrypted remote protocol stays 2).
-- Add an eye toggle for read-only mobile remote previews of Markdown, HTML with sandboxed JavaScript, images, audio, video and PDFs, including bounded local assets and custom browse roots (daemon/cockpit protocol 21.1).
+## [0.2.7] — 2026-09-23
 
 ### Changed
 
-- Move the mobile session sidebar and its expanded drawer to the left, with matching collapse/expand icons.
+- Allow an empty project default base branch to follow the branch currently checked out at the clone location for each new agent or terminal; retain explicit branch choices (daemon/cockpit protocol 21.3; remote protocol remains 2).
 
 ### Fixed
 
-- Retire deleted and replaced remote registrations from the relay, retry cleanup across outages/restarts, and expose confirmed removal of legacy phantom hosts in remote settings (daemon/cockpit protocol 21.0; encrypted remote protocol stays 2).
-- Keep the current protocol assertion separate from schema tests and verify that older daemons require an upgrade.
+- Fix CI deployment validation by creating a private temporary service environment file from the checked-in example before resolving the Compose configuration.

package/README.md

@@ -20,7 +20,27 @@ Puddle manages parallel agents anywhere you SSH into, insulates agents in dedica
 
 ## Quick start
 
-**On your local machine where you will be using the GUI, run:**
+**On your local machine where you will be using the GUI:**
+
+For a standalone installation without Node.js or npm, use your deployed app's
+installer (replace the example host):
+
+```sh
+curl -fsSL https://app.example.com/install.sh | sh
+```
+
+This installs the CLI under `~/.local/share/puddle/cli` and its launcher at
+`~/.local/bin/puddle`. Add `~/.local/bin` to your `PATH` if the installer asks.
+The standalone releases support Linux x64/arm64 and macOS arm64. The script and
+checksum-verified archives are also attached to this repository's GitHub Releases.
+An optional `--version` selects a release; `--prefix` and `--bin-dir` select the
+installation and launcher directories:
+
+```sh
+curl -fsSL https://app.example.com/install.sh | sh -s -- --version X.Y.Z
+```
+
+Alternatively, with Node.js already installed, use npm:
 
 ```sh
 npm install -g @puddle-code/cli
@@ -56,13 +76,11 @@ detached processes, Puddle instead keeps the daemon attached to the cockpit; clo
 live processes. The next `puddle launch` restarts the daemon from the host's persistent state and,
 when auto-resume is enabled (the default), restores the interrupted sessions.
 
-**Daemon-only installs:**
-
-Daemon-only installs (no CLI) use the `install.sh` attached to each release — see the Releases page of this repository:
-
-```sh
-curl -fsSL https://github.com/PerceptronV/puddle-code/releases/latest/download/install.sh | sh
-```
+The [deployed app](docs/mobile-access.md#host-the-installer) serves `/install.sh`
+as the single public installer. Install daemon and desktop components through
+`puddle install daemon [user@host]` and `puddle install desktop`. A first
+`puddle launch user@host` still installs a missing daemon automatically from
+GitHub Releases.
 
 **Managing components:**
 
@@ -76,21 +94,13 @@ puddle remove daemon                      # uninstall; your data stays unless yo
 
 **Desktop app (optional):**
 
-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. Grab the dmg (macOS arm64) or AppImage (Linux x64) from the Releases page.
+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). Once installed, it runs independently of the CLI.
 
 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.
 
-The macOS downloads are **not code-signed** (an open-source project without Apple Developer Program fees), so Gatekeeper will refuse the first launch. Either allow it once — open the app, let macOS block it, then System Settings → Privacy & Security → **Open Anyway** — or clear the download quarantine in a terminal:
-
-```sh
-xattr -dr com.apple.quarantine /Applications/Puddle.app
-```
-
-Building from source avoids the dance entirely (locally built apps are never quarantined): `pnpm build && pnpm --filter @puddle/desktop dist`.
-
 **Host requirements**: Linux with glibc 2.28+ (Ubuntu 20.04+, Debian 11+, RHEL/Rocky 8+;
 Alpine is not supported) or macOS, with `git` and `curl`, plus whichever agent CLIs you want on
-`PATH`. The client side works from any OS with a browser and `ssh` (Windows works, with repeated
+`PATH`. Standalone CLI installs include Node and require no npm; npm installs require Node 22+. The client side works from any OS with a browser and `ssh` (Windows works, with repeated
 auth prompts unless you use a key).
 
 ## How it works
@@ -113,7 +123,7 @@ auth prompts unless you use a key).
                                         └───────────────────────────────────┘
 ```
 
-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 (`npm update -g @puddle-code/cli` refreshes the cockpit for every host); the daemon only has to update when the versioned protocol breaks, and the CLI does that automatically. 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.
+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 (`puddle upgrade cli` refreshes the cockpit for every host); the daemon only has to update when the versioned protocol breaks, and the launcher asks for approval before updating it. The prompt shows the host, both protocols and how many live sessions the restart interrupts; 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.
 
 Everything lives under `~/.puddle` on the host, installed without sudo — and `puddle remove daemon` takes it apart again.
 
@@ -121,14 +131,14 @@ Everything lives under `~/.puddle` on the host, installed without sudo — and `
 
 **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. They never run side by side, and there is no separate "dev daemon" alongside a "production daemon".
 
-**Dev build vs. production.** `npm i -g @puddle-code/cli` is the production path — its `puddle` fetches and upgrades the daemon from this repo's GitHub Releases. To exercise uncommitted changes, build and run from the repo:
+**Dev build vs. production.** The standalone installer or `npm i -g @puddle-code/cli` is the production path — its `puddle` fetches and upgrades the daemon from this repo's GitHub Releases. To exercise uncommitted changes, build and run from the repo:
 
 ```sh
 pnpm build && pnpm build:tarball
-node packages/cli/dist/index.js start --tarball dist-release/puddled-v*.tar.gz --foreground
+node packages/cli/dist/index.js launch --tarball dist-release/puddled-v*.tar.gz --foreground
 ```
 
-`--tarball` sets the install _source_ only, and is consulted **only when the CLI actually installs the daemon** — when none is running, the daemon is stopped, or a protocol-major upgrade fires. If a compatible daemon (same protocol major) is already up, `start` just serves the cockpit against it and **the tarball is ignored** (even a newer app version — nothing compares app versions). So to load a fresh dev build over a running daemon you must **stop it first** (see _Kill_ below), then re-run `start --tarball …`. `--foreground` keeps the cockpit attached (`connect <user>@<host> --tarball …` is the remote form). Both clients share one `~/.puddle` daemon and cockpit registry, so `puddle list` / `puddle kill` see either — don't point both at the same host at once. (Never launch the daemon from inside a coding-agent shell: it inherits the agent's env and breaks conversation resume — use a plain terminal.)
+`--tarball` sets the install _source_ only, and is consulted **only when the CLI actually installs the daemon** — when none is running, the daemon is stopped, or a protocol-major upgrade fires. If a compatible daemon (same protocol major) is already up, `launch` just serves the cockpit against it and **the tarball is ignored** (even a newer app version — nothing compares app versions). So to load a fresh dev build over a running daemon you must **stop it first** (see _Kill_ below), then re-run `launch --tarball …`. `--foreground` keeps the cockpit attached (`launch <user>@<host> --tarball …` is the remote form). Both clients share one `~/.puddle` daemon and cockpit registry, so `puddle list` / `puddle kill` see either — don't point both at the same host at once. (Never launch the daemon from inside a coding-agent shell: it inherits the agent's env and breaks conversation resume — use a plain terminal.)
 
 **Kill.** `puddle kill --all` (or Ctrl-C in a `--foreground` run) normally stops the local cockpit
 UI only; a supervised daemon and its sessions keep running. When launch reported that it is keeping
@@ -150,7 +160,7 @@ kill "$(cat ~/.puddle/puddled.pid)"                 # nohup fallback (no supervi
 
 ```sh
 puddle remove daemon --purge   # stops the daemon, unregisters its service, deletes ~/.puddle
-puddle remove cli              # npm uninstall -g, once the daemons you care about are gone
+puddle remove cli              # standalone or npm removal, using its installation channel
 ```
 
 > ⚠️ `~/.puddle` **is** your local state — the SQLite database with every profile, account, and session (plus conversation history), the daemon's worktree tracking, and the auth token. `--purge` deletes it irreversibly (the command lists dirty or unpushed worktrees and asks first); without it, `puddle remove daemon` keeps the data for a later reinstall.

package/dist/host-control.mjs

@@ -14834,6 +14834,7 @@ var agentTypeSchema = external_exports.object({
 var repoSchema = external_exports.object({
   id: rowId,
   path: external_exports.string(),
+  /** Empty follows the branch currently checked out at path, resolved for each new session. */
   default_base_branch: external_exports.string(),
   onboarding_notes: external_exports.string().nullable(),
   fetch_enabled: external_exports.boolean(),
@@ -14844,7 +14845,8 @@ var repoWithOrphansSchema = repoSchema.extend({
 });
 var createRepoRequestSchema = external_exports.object({
   path: external_exports.string().min(1),
-  default_base_branch: external_exports.string().min(1).optional(),
+  /** Empty follows the clone's current branch; omitted snapshots it at registration. */
+  default_base_branch: external_exports.string().optional(),
   onboarding_notes: external_exports.string().nullable().optional(),
   fetch_enabled: external_exports.boolean().optional()
 });
@@ -14885,7 +14887,8 @@ var repoWorktreesResponseSchema = external_exports.object({
   orphan_branches: external_exports.array(orphanBranchSchema)
 });
 var patchRepoRequestSchema = external_exports.object({
-  default_base_branch: external_exports.string().min(1).optional(),
+  /** Empty follows the clone's current branch; omitted leaves the setting unchanged. */
+  default_base_branch: external_exports.string().optional(),
   onboarding_notes: external_exports.string().nullable().optional(),
   fetch_enabled: external_exports.boolean().optional()
 });
@@ -16241,7 +16244,7 @@ async function inspectLegacyHost(home) {
   };
   try {
     const version2 = versionResponseSchema.parse(await get("/api/version"));
-    const sessions = sessionSchema.array().parse(await get("/api/sessions"));
+    const sessions = sessionSchema.pick({ status: true }).array().parse(await get("/api/sessions"));
     return hostInspectionSchema.parse({
       t: "inspection",
       port,
@@ -16286,7 +16289,7 @@ async function inspectHostLocally(home) {
       signal: AbortSignal.timeout(3e3)
     });
     if (!response.ok) throw new Error("Host inspection rejected");
-    const sessions = sessionSchema.array().parse(await response.json());
+    const sessions = sessionSchema.pick({ status: true }).array().parse(await response.json());
     return hostInspectionSchema.parse({
       t: "inspection",
       port: grant.port,