@puddle-code/cli 0.0.1 → 0.0.3

package/dist/index.js

@@ -3908,9 +3908,12 @@ init_types();
 var USAGE = `puddle \u2014 self-hosted orchestrator for CLI coding agents
 
 usage:
-  puddle start   [--port <p>] [--no-browser] [--no-upgrade] [--tarball <path>]
-  puddle connect user@host [--port <local>] [--remote-port <p>] [--no-browser]
-                 [--no-upgrade] [--tarball <path>]
+  puddle start   [--port <p>] [--foreground] [--no-browser] [--no-upgrade]
+                 [--tarball <path>]
+  puddle connect user@host [--port <local>] [--remote-port <p>] [--foreground]
+                 [--no-browser] [--no-upgrade] [--tarball <path>]
+  puddle list
+  puddle kill    [local | user@host | --all]
   puddle status  [user@host]
   puddle attach  [user@host] <session> [--term <id>]
   puddle logs    [user@host] [session] [--term <id>] [-f|--follow]
@@ -3919,8 +3922,10 @@ usage:
 
 start serves the cockpit at http://localhost:7433 against the daemon on this
 machine (installing it under ~/.puddle if needed); connect does the same for
-an SSH host through one tunnel. Ctrl-C stops the cockpit only \u2014 sessions keep
-running on the host.`;
+an SSH host through one tunnel. Both keep running in the background once
+ready, so the terminal may close (--foreground to stay attached; Ctrl-C then
+stops the cockpit). list shows running cockpits; kill stops one \u2014 sessions
+keep running on the host either way.`;
 function parseArgs(argv) {
   const [cmd, ...rest] = argv;
   if (cmd === void 0 || cmd === "help" || cmd === "--help" || cmd === "-h")
@@ -3977,13 +3982,14 @@ function parseArgs(argv) {
       }
       const port = intFlag("--port");
       const tarball = strFlag("--tarball");
-      expect("--port", "--no-browser", "--no-upgrade", "--tarball");
+      expect("--port", "--no-browser", "--no-upgrade", "--tarball", "--foreground");
       return {
         cmd: "start",
         ...port !== void 0 ? { port } : {},
         ...tarball !== void 0 ? { tarball } : {},
         noBrowser: flags.has("--no-browser"),
-        noUpgrade: flags.has("--no-upgrade")
+        noUpgrade: flags.has("--no-upgrade"),
+        foreground: flags.has("--foreground")
       };
     }
     case "connect": {
@@ -3995,7 +4001,14 @@ function parseArgs(argv) {
       const port = intFlag("--port");
       const remotePort = intFlag("--remote-port");
       const tarball = strFlag("--tarball");
-      expect("--port", "--remote-port", "--no-browser", "--no-upgrade", "--tarball");
+      expect(
+        "--port",
+        "--remote-port",
+        "--no-browser",
+        "--no-upgrade",
+        "--tarball",
+        "--foreground"
+      );
       return {
         cmd: "connect",
         host,
@@ -4003,9 +4016,26 @@ function parseArgs(argv) {
         ...remotePort !== void 0 ? { remotePort } : {},
         ...tarball !== void 0 ? { tarball } : {},
         noBrowser: flags.has("--no-browser"),
-        noUpgrade: flags.has("--no-upgrade")
+        noUpgrade: flags.has("--no-upgrade"),
+        foreground: flags.has("--foreground")
       };
     }
+    case "list": {
+      if (positionals.length > 0)
+        throw new CliError("bad_arguments", "list takes no positional arguments");
+      expect();
+      return { cmd: "list" };
+    }
+    case "kill": {
+      if (positionals.length > 1)
+        throw new CliError("bad_arguments", "kill takes at most one target");
+      expect("--all");
+      const all = flags.has("--all");
+      const target = positionals[0];
+      if (all && target !== void 0)
+        throw new CliError("bad_arguments", "kill takes a target or --all, not both");
+      return { cmd: "kill", all, ...target !== void 0 ? { target } : {} };
+    }
     case "status": {
       if (positionals.length > 1)
         throw new CliError("bad_arguments", "status takes at most a host");
@@ -4062,7 +4092,7 @@ function parseArgs(argv) {
 // src/cli/run.ts
 init_attach();
 import { existsSync as existsSync3 } from "node:fs";
-import { dirname as dirname4, join as join5 } from "node:path";
+import { dirname as dirname5, join as join6 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/lib/browser.ts
@@ -4081,7 +4111,7 @@ function openBrowser(url2, platform = process.platform) {
 }
 
 // ../shared/src/protocol.ts
-var PROTOCOL_VERSION = { major: 5, minor: 1 };
+var PROTOCOL_VERSION = { major: 6, minor: 2 };
 
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -18627,7 +18657,14 @@ var fields = {
   logMaxBytes: external_exports.number().int().min(64 * 1024),
   replayBytes: external_exports.number().int().min(1024),
   /** Days a (project, profile) ui_state row survives without an update. */
-  uiStateRetentionDays: external_exports.number().int().min(1)
+  uiStateRetentionDays: external_exports.number().int().min(1),
+  /**
+   * Colon-separated dirs prepended to the daemon's PATH so it can find agent
+   * CLIs even under a supervisor with a bare PATH (launchd/systemd). Leading `~`
+   * expands to the daemon user's home. Covers Claude Code's native-installer
+   * location (`~/.local/bin`). Takes effect on the next daemon start.
+   */
+  agentPath: external_exports.string()
 };
 var daemonConfigSchema = external_exports.object({
   port: fields.port.default(7434),
@@ -18635,7 +18672,8 @@ var daemonConfigSchema = external_exports.object({
   fetchIntervalMinutes: fields.fetchIntervalMinutes.default(15),
   logMaxBytes: fields.logMaxBytes.default(10 * 1024 * 1024),
   replayBytes: fields.replayBytes.default(256 * 1024),
-  uiStateRetentionDays: fields.uiStateRetentionDays.default(90)
+  uiStateRetentionDays: fields.uiStateRetentionDays.default(90),
+  agentPath: fields.agentPath.default("~/.local/bin:~/bin:/opt/homebrew/bin:/usr/local/bin")
 });
 var daemonConfigPatchSchema = external_exports.object(fields).partial();
 
@@ -18659,6 +18697,17 @@ var hostInfoSchema = external_exports.object({
 
 // ../shared/src/api/profiles.ts
 var fsSafeName = external_exports.string().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "letters, digits, dot, underscore and hyphen only");
+var RULES_TOKEN = "{{rules}}";
+var DEFAULT_ONBOARDING_TEMPLATE = `[puddle onboarding] This is a freshly created git worktree for this task. Before starting, set up the environment:
+
+1. Standing setup rules for this repository (user-authored):
+${RULES_TOKEN}
+
+2. Inspect the codebase for setup requirements (README, CONTRIBUTING, lockfiles, .tool-versions, pyproject.toml, package.json, \u2026).
+3. Apply what the rules above settle without asking. Ask the user about anything they leave open, stating trade-offs where relevant (e.g. a symlinked .venv saves gigabytes per worktree, but parallel sessions then share mutable dependency state).
+4. If the user states a standing rule for all future worktrees ("always\u2026", "never\u2026", "from now on\u2026"), write the complete updated rules to \`.puddle/onboarding-notes.md\` in this worktree \u2014 full replacement, user-owned prose; record their decision, don't invent policy.
+
+Then proceed with the task below (or await instructions if none is given).`;
 var profileSchema = external_exports.object({
   id: profileId,
   name: fsSafeName,
@@ -18670,10 +18719,36 @@ var createProfileRequestSchema = external_exports.object({
   branch_prefix: external_exports.string().max(64).optional()
 });
 var patchProfileRequestSchema = external_exports.object({
-  branch_prefix: external_exports.string().max(64)
+  name: fsSafeName.optional(),
+  branch_prefix: external_exports.string().max(64).optional()
 });
 var profileSettingsSchema = external_exports.looseObject({
-  allowSkipPermissions: external_exports.boolean().default(false)
+  allowSkipPermissions: external_exports.boolean().default(false),
+  /**
+   * Launch-text templates (SPEC §4). A key that is ABSENT falls back to the
+   * daemon's built-in default; an EMPTY string is an intentional empty preamble.
+   * `onboardingTemplate` (freshly created worktree) supports a `{{rules}}` token
+   * where the repo's onboarding notes are injected; `concurrentTemplate` is used
+   * when a session joins an existing/shared worktree; `restartTemplate` is sent
+   * when a session is resumed after a daemon restart or machine reboot.
+   */
+  onboardingTemplate: external_exports.string().optional(),
+  concurrentTemplate: external_exports.string().optional(),
+  restartTemplate: external_exports.string().optional(),
+  /**
+   * How a session's tab/label is composed from its parts (SPEC §4). A template
+   * string interpolating `${…}` variables (see `TAB_TITLE_VARIABLES`); ABSENT
+   * falls back to `DEFAULT_TAB_TITLE_TEMPLATE` (`${name}`), reproducing the
+   * historical display name. Empty renders (all chosen variables blank) fall
+   * back to the session-id prefix, so a tab is never nameless.
+   */
+  tabTitleTemplate: external_exports.string().optional(),
+  /**
+   * The user's drag-order of projects on the homescreen (project ids). Projects
+   * absent from this list — newly created ones — sort to the top. The right
+   * sidebar's cross-project grouping inherits this order (SPEC §11, §12).
+   */
+  projectOrder: external_exports.array(external_exports.string()).optional()
 });
 var patchProfileSettingsRequestSchema = external_exports.record(external_exports.string(), external_exports.unknown());
 
@@ -18836,7 +18911,24 @@ var sessionSchema = external_exports.object({
   /** Null for terminal sessions, which run a plain shell rather than an agent. */
   agent_type: external_exports.string().nullable(),
   agent_session_ref: external_exports.string().nullable(),
+  /** User-set display override; null means "use the agent's own name" (agent_title) then the id. */
   title: external_exports.string().nullable(),
+  /**
+   * The agent's own session name (for Claude Code, the transcript's ai-title /
+   * agent-name — the name shown in its resume picker), maintained by the daemon.
+   * The default display name when the user has not set a `title`. Optional:
+   * older daemons omit it; null when the agent has not named the session yet.
+   */
+  agent_title: external_exports.string().nullable().optional(),
+  /**
+   * The terminal-title "sequence" name: the last title the process set on its
+   * PTY via an OSC 0/1/2 escape, normalised (leading spinner/status glyphs
+   * stripped). This is the VSCode `${sequence}` variable — a name source for
+   * agents and terminals that have no adapter-maintained `agent_title`. Optional:
+   * older daemons omit it; null when the process has set no title. It never
+   * overrides a user `title`; see `tabTitleTemplate` for how it is composed.
+   */
+  osc_title: external_exports.string().nullable().optional(),
   status: sessionStatusSchema,
   skip_permissions: external_exports.boolean(),
   created_at: isoTimestamp,
@@ -18898,7 +18990,7 @@ var createSessionRequestSchema = external_exports.object({
   prompt: external_exports.string().optional(),
   skip_permissions: external_exports.boolean().optional()
 });
-var patchSessionRequestSchema = external_exports.object({ title: external_exports.string().min(1).max(200) });
+var patchSessionRequestSchema = external_exports.object({ title: external_exports.string().max(200) });
 var migrateSessionRequestSchema = external_exports.object({ account_id: rowId });
 var archiveRequestSchema = external_exports.object({
   force: external_exports.boolean().default(false),
@@ -18916,6 +19008,12 @@ var projectSchema = external_exports.object({
   profile_id: profileId,
   repo_id: rowId,
   name: external_exports.string(),
+  /**
+   * Hidden from the homescreen but never deleted — every session, worktree, and
+   * bit of data is retained, and un-archiving restores it all (SPEC §11).
+   * Defaults false so an older daemon that omits it reads as not-archived.
+   */
+  archived: external_exports.boolean().default(false),
   created_at: isoTimestamp,
   updated_at: isoTimestamp
 });
@@ -18924,6 +19022,10 @@ var createProjectRequestSchema = external_exports.object({
   repo_id: rowId,
   name: external_exports.string().min(1).max(100)
 });
+var patchProjectRequestSchema = external_exports.object({
+  name: external_exports.string().min(1).max(100).optional(),
+  archived: external_exports.boolean().optional()
+});
 var projectDetailSchema = external_exports.object({
   project: projectSchema,
   sessions: external_exports.array(sessionSchema)
@@ -18936,6 +19038,29 @@ var editorTabRefSchema = external_exports.object({
   kind: external_exports.enum(["file", "diff", "commit"]).optional(),
   sha: external_exports.string().optional()
 });
+var tabRefSchema = external_exports.discriminatedUnion("type", [
+  external_exports.object({ type: external_exports.literal("editor"), tab: editorTabRefSchema }),
+  external_exports.object({ type: external_exports.literal("terminal"), session: sessionId })
+]);
+var layoutLeafSchema = external_exports.object({
+  kind: external_exports.literal("leaf"),
+  id: external_exports.string(),
+  tabs: external_exports.array(tabRefSchema).default([]),
+  activeKey: external_exports.string().nullable().default(null),
+  previewKey: external_exports.string().nullable().default(null)
+});
+var layoutNodeSchema = external_exports.lazy(
+  () => external_exports.discriminatedUnion("kind", [
+    layoutLeafSchema,
+    external_exports.object({
+      kind: external_exports.literal("split"),
+      id: external_exports.string(),
+      direction: external_exports.enum(["row", "col"]),
+      children: external_exports.array(layoutNodeSchema),
+      sizes: external_exports.array(external_exports.number())
+    })
+  ])
+);
 var uiStateSnapshotSchema = external_exports.looseObject({
   session_tabs: external_exports.array(sessionId).default([]),
   active_session: sessionId.nullable().default(null),
@@ -18962,7 +19087,13 @@ var uiStateSnapshotSchema = external_exports.looseObject({
    * listed here (newly created ones) sort to the top; the list is otherwise
    * drag-reorderable and this persists it (SPEC §8).
    */
-  session_order: external_exports.array(sessionId).default([])
+  session_order: external_exports.array(sessionId).default([]),
+  /**
+   * The tiling layout tree (SPEC §8): the source of truth for which tabs are
+   * open and where. Null on legacy snapshots — the web rebuilds an equivalent
+   * tree from `editor_tabs`/`session_tabs`/`layout` on first load.
+   */
+  layout_tree: layoutNodeSchema.nullable().default(null)
 });
 var putProjectStateRequestSchema = external_exports.object({
   ui_state: uiStateSnapshotSchema
@@ -19028,6 +19159,27 @@ var uploadResponseSchema = external_exports.object({
   )
 });
 
+// ../shared/src/api/worktree-fs.ts
+var createEntryRequestSchema = external_exports.object({
+  path: external_exports.string().min(1),
+  kind: external_exports.enum(["file", "dir"])
+});
+var renameEntryRequestSchema = external_exports.object({
+  from: external_exports.string().min(1),
+  to: external_exports.string().min(1)
+});
+var copyEntryRequestSchema = external_exports.object({
+  from: external_exports.string().min(1),
+  to: external_exports.string().min(1)
+});
+var deleteEntryRequestSchema = external_exports.object({
+  path: external_exports.string().min(1)
+});
+var fsOpResponseSchema = external_exports.object({
+  ok: external_exports.literal(true),
+  path: external_exports.string()
+});
+
 // ../shared/src/api/worktree-git.ts
 var diffStatusSchema = external_exports.enum(["added", "modified", "deleted", "renamed"]);
 var diffEntrySchema = external_exports.object({
@@ -19043,6 +19195,22 @@ var diffResponseSchema = external_exports.object({
   base_ref: external_exports.string().nullable(),
   entries: external_exports.array(diffEntrySchema)
 });
+var gitStatusSchema = external_exports.enum([
+  "untracked",
+  "modified",
+  "added",
+  "deleted",
+  "renamed",
+  "conflicted",
+  "ignored"
+]);
+var gitStatusEntrySchema = external_exports.object({
+  path: external_exports.string(),
+  status: gitStatusSchema
+});
+var gitStatusResponseSchema = external_exports.object({
+  entries: external_exports.array(gitStatusEntrySchema)
+});
 var fileAtResponseSchema = external_exports.object({
   path: external_exports.string(),
   ref: external_exports.string(),
@@ -19154,6 +19322,18 @@ async function waitForTcp(port, timeoutMs) {
   }
   return false;
 }
+async function waitForHttp(url2, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      await fetch(url2, { signal: AbortSignal.timeout(2e3) });
+      return true;
+    } catch {
+      await sleep(250);
+    }
+  }
+  return false;
+}
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
@@ -19169,6 +19349,7 @@ var hostPaths = {
   home: HOST_HOME,
   token: `${HOST_HOME}/token`,
   config: `${HOST_HOME}/config.json`,
+  runtime: `${HOST_HOME}/runtime.json`,
   current: `${HOST_HOME}/bin/current`,
   cache: `${HOST_HOME}/cache`,
   logs: `${HOST_HOME}/logs`
@@ -19233,6 +19414,14 @@ var DaemonClient = class {
   }
 };
 async function readDaemonPort(transport) {
+  const runtime = await transport.readFile(hostPaths.runtime);
+  if (runtime !== null) {
+    try {
+      const parsed = JSON.parse(runtime);
+      if (typeof parsed.port === "number") return parsed.port;
+    } catch {
+    }
+  }
   const raw = await transport.readFile(hostPaths.config);
   if (raw !== null) {
     try {
@@ -19273,7 +19462,7 @@ import { readFileSync } from "node:fs";
 import { dirname, join as join2 } from "node:path";
 import { fileURLToPath } from "node:url";
 function cliVersion() {
-  if (true) return "0.0.1";
+  if (true) return "0.0.3";
   const here = dirname(fileURLToPath(import.meta.url));
   for (const candidate of [
     join2(here, "..", "..", "package.json"),
@@ -19330,18 +19519,18 @@ async function installDaemon(transport, opts = {}) {
       }
     }
   } else {
-    const slug = repoSlug();
+    const slug2 = repoSlug();
     if (opts.tarball !== void 0) {
       throw new CliError("bad_arguments", "--tarball must be a local file path");
     }
-    if (slug === void 0) {
+    if (slug2 === void 0) {
       throw new CliError(
         "not_installed",
         "no release source is configured for this build",
         "pass --tarball <path> (pnpm build:tarball produces one) or set PUDDLE_REPO=owner/repo"
       );
     }
-    args.push("--repo", slug);
+    args.push("--repo", slug2);
   }
   logger.info(`installing puddled ${version2} on ${transport.label}`);
   const quoted = args.map((a) => `'${a.replaceAll("'", `'\\''`)}'`).join(" ");
@@ -19387,42 +19576,63 @@ async function ensureDaemon(transport, opts) {
     await installDaemon(transport, opts);
     bootstrapped = true;
     token = await waitForToken(transport, 2e4);
+    const up = await waitForHostProbe(transport, token, 2e4);
+    if (up.result === "unauthorised") throw portConflict(transport, up.port);
+    if (up.result !== "ok") throw startTimeout(transport);
+    return { port: up.port, token, bootstrapped };
   }
   let port = await readDaemonPort(transport);
-  if (!await hostProbe(transport, port)) {
+  const probe = await hostProbe(transport, port, token);
+  if (probe === "unauthorised") throw portConflict(transport, port);
+  if (probe === "down") {
     if (await installedVersion(transport) === null) {
-      throw new CliError(
-        "daemon_unreachable",
-        `a puddle state directory exists on ${transport.label} but no managed daemon answers on port ${port}`,
-        "a development daemon must be started by hand; otherwise remove ~/.puddle/bin and re-run to bootstrap"
-      );
+      logger.info(`no managed daemon on ${transport.label} \u2014 bootstrapping one`);
+    } else {
+      logger.info(`puddled is installed on ${transport.label} but not running \u2014 restarting it`);
     }
-    logger.info(`puddled is installed on ${transport.label} but not running \u2014 restarting it`);
     await installDaemon(transport, opts);
     bootstrapped = true;
-    port = await readDaemonPort(transport);
-    if (!await waitForHostProbe(transport, port, 2e4)) {
-      throw new CliError(
-        "daemon_start_timeout",
-        `puddled did not come up on ${transport.label}`,
-        transport.kind === "ssh" ? `inspect it with: puddle logs ${transport.label}` : "inspect it with: puddle logs"
-      );
-    }
+    token = await readToken(transport) ?? token;
+    const after = await waitForHostProbe(transport, token, 2e4);
+    if (after.result === "unauthorised") throw portConflict(transport, after.port);
+    if (after.result !== "ok") throw startTimeout(transport);
+    port = after.port;
   }
   return { port, token, bootstrapped };
 }
-async function hostProbe(transport, port) {
-  const cmd = `(command -v curl >/dev/null 2>&1 && curl -s -o /dev/null --max-time 2 http://127.0.0.1:${port}/api/version && echo OK) || (command -v bash >/dev/null 2>&1 && bash -c 'exec 3<>/dev/tcp/127.0.0.1/${port}' 2>/dev/null && echo OK) || true`;
-  const result = await transport.exec(cmd, { timeoutMs: 1e4 });
-  return result.stdout.includes("OK");
+function startTimeout(transport) {
+  return new CliError(
+    "daemon_start_timeout",
+    `puddled did not come up on ${transport.label}`,
+    transport.kind === "ssh" ? `inspect it with: puddle logs ${transport.label}` : "inspect it with: puddle logs"
+  );
+}
+function portConflict(transport, port) {
+  return new CliError(
+    "port_in_use",
+    `something on ${transport.label} answers on 127.0.0.1:${port} but rejects this host's token`,
+    `it is probably not this host's daemon \u2014 another puddle cockpit's UI server that auto-picked ${port}, or a daemon started before the token changed. Close it (or restart it), or point the daemon at another port in ~/.puddle/config.json.`
+  );
 }
-async function waitForHostProbe(transport, port, timeoutMs) {
+async function hostProbe(transport, port, token) {
+  const cmd = `if command -v curl >/dev/null 2>&1; then curl -s -o /dev/null --max-time 2 -w 'HTTP:%{http_code}' -H 'Authorization: Bearer ${token}' http://127.0.0.1:${port}/api/version || echo DOWN; elif command -v bash >/dev/null 2>&1 && bash -c 'exec 3<>/dev/tcp/127.0.0.1/${port}' 2>/dev/null; then echo TCPOPEN; else echo DOWN; fi`;
+  const out = (await transport.exec(cmd, { timeoutMs: 1e4 })).stdout;
+  if (out.includes("HTTP:200")) return "ok";
+  if (out.includes("HTTP:401") || out.includes("HTTP:403")) return "unauthorised";
+  if (out.includes("TCPOPEN")) return "ok";
+  return "down";
+}
+async function waitForHostProbe(transport, token, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
+  let last = "down";
+  let port = await readDaemonPort(transport);
   while (Date.now() < deadline) {
-    if (await hostProbe(transport, port)) return true;
+    port = await readDaemonPort(transport);
+    last = await hostProbe(transport, port, token);
+    if (last !== "down") return { result: last, port };
     await sleep(500);
   }
-  return false;
+  return { result: last, port };
 }
 function makeUpgrader(transport, client, opts) {
   return async () => {
@@ -19484,6 +19694,7 @@ async function runHandshake(opts) {
 
 // src/lib/serve/ui-server.ts
 init_types();
+import { randomUUID } from "node:crypto";
 import { createServer as createServer2 } from "node:http";
 
 // src/lib/serve/guard.ts
@@ -19504,6 +19715,24 @@ function isLocalOrigin(origin) {
   }
 }
 
+// src/lib/serve/proxy-recovery.ts
+var PROXY_PAGE = /^\/proxy\/([^/]+)\/(\d+)(?:\/|$)/;
+function recoverProxiedPath(referer, requestUrl) {
+  if (typeof referer !== "string" || !requestUrl.startsWith("/")) return null;
+  const pathname = requestUrl.split("?")[0] ?? "";
+  if (pathname === "/proxy" || pathname.startsWith("/proxy/")) return null;
+  let ref;
+  try {
+    ref = new URL(referer);
+  } catch {
+    return null;
+  }
+  if (!isLocalHostHeader(ref.host)) return null;
+  const match = PROXY_PAGE.exec(ref.pathname);
+  if (match === null) return null;
+  return `/proxy/${match[1]}/${match[2]}${requestUrl}`;
+}
+
 // src/lib/serve/static.ts
 import { createReadStream, existsSync as existsSync2, statSync } from "node:fs";
 import { extname, join as join4, normalize, resolve as resolve2, sep } from "node:path";
@@ -19527,9 +19756,21 @@ function createStaticHandler(rootDir) {
       return;
     }
     const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
-    const requested = normalize(join4(root, decodeURIComponent(pathname)));
+    let decoded;
+    try {
+      decoded = decodeURIComponent(pathname);
+    } catch {
+      res.writeHead(404, { "content-type": "text/plain" }).end("not found");
+      return;
+    }
+    const requested = normalize(join4(root, decoded));
     const candidate = requested.startsWith(root + sep) || requested === root ? requested : root;
-    const file2 = existsSync2(candidate) && statSync(candidate).isFile() ? candidate : join4(root, "index.html");
+    const isFile = existsSync2(candidate) && statSync(candidate).isFile();
+    if (!isFile && extname(pathname) !== "") {
+      res.writeHead(404, { "content-type": "text/plain" }).end("not found");
+      return;
+    }
+    const file2 = isFile ? candidate : join4(root, "index.html");
     if (!existsSync2(file2)) {
       res.writeHead(404, { "content-type": "text/plain" }).end("not found");
       return;
@@ -19691,8 +19932,16 @@ async function startUiServer(opts) {
   const target = { ...opts.target };
   const tracker = new ProxySocketTracker();
   const serveStatic = createStaticHandler(opts.assetsDir);
+  const nonce = randomUUID();
   const server = createServer2((req, res) => {
+    res.setHeader("x-puddle-cockpit", nonce);
     const url2 = req.url ?? "/";
+    const recovered = recoverProxiedPath(req.headers.referer, url2);
+    if (recovered !== null) {
+      res.writeHead(307, { location: recovered });
+      res.end();
+      return;
+    }
     if (isProxiedPath(url2)) {
       if (!isLocalHostHeader(req.headers.host) || !isLocalOrigin(req.headers.origin)) {
         res.writeHead(403, { "content-type": "application/json" });
@@ -19715,10 +19964,16 @@ async function startUiServer(opts) {
     }
     proxyUpgrade(req, socket, head, target, tracker);
   });
-  const port = await listen(server, opts.port ?? DEFAULT_UI_PORT, opts.strictPort ?? false);
+  const port = await listen(
+    server,
+    opts.port ?? DEFAULT_UI_PORT,
+    opts.strictPort ?? false,
+    opts.avoidPort
+  );
   return {
     port,
     origin: `http://localhost:${port}`,
+    nonce,
     setTarget(next) {
       target.host = next.host;
       target.port = next.port;
@@ -19732,9 +19987,10 @@ async function startUiServer(opts) {
     }
   };
 }
-async function listen(server, startPort, strict) {
+async function listen(server, startPort, strict, avoidPort) {
   for (let probe = 0; probe < MAX_PORT_PROBES; probe += 1) {
     const port = startPort + probe;
+    if (!strict && port === avoidPort) continue;
     const ok = await new Promise((resolve3, rejectListen) => {
       const onError = (err) => {
         server.off("listening", onListening);
@@ -19769,71 +20025,122 @@ import { spawn as spawn2 } from "node:child_process";
 init_types();
 var RECONNECT_INITIAL_MS = 500;
 var RECONNECT_MAX_MS = 1e4;
+var DOWN_GRACE_MS = 2e3;
+var STABLE_MS = 3e4;
+var HEALTH_INTERVAL_MS = 1e3;
 async function openTunnel(ssh, remotePort, opts = {}) {
   const logger = opts.logger ?? silentLogger;
   const sshBinary = opts.sshBinary ?? "ssh";
+  const downGraceMs = opts.downGraceMs ?? DOWN_GRACE_MS;
+  const healthIntervalMs = opts.healthIntervalMs ?? HEALTH_INTERVAL_MS;
+  const isReady = opts.ready ?? (() => Promise.resolve(true));
   const eventCbs = /* @__PURE__ */ new Set();
   const portCbs = /* @__PURE__ */ new Set();
   const emit = (e) => eventCbs.forEach((cb) => cb(e));
   let localPort = await findFreePort();
   const state = { child: null };
   let stopping = false;
+  let lastRestoredAt = 0;
+  let reconnectActive = false;
+  let healthTimer = null;
   const spawnForward = async (port) => {
+    if (stopping) return false;
     const child = spawn2(
       sshBinary,
       ssh.args("-N", "-L", `${port}:127.0.0.1:${remotePort}`, ssh.host),
-      {
-        stdio: ["ignore", "ignore", "inherit"]
-      }
+      { stdio: ["ignore", "ignore", "inherit"] }
     );
-    child.on("close", onChildExit);
     state.child = child;
-    return waitForTcp(port, 5e3);
+    const ready = await waitForTcp(port, 5e3) && await isReady(port);
+    if (!ready) discard(child, port);
+    return ready;
   };
-  const onChildExit = () => {
+  const discard = (child, port) => {
+    if (state.child === child) state.child = null;
+    child.kill("SIGTERM");
+    void ssh.cancelForward(port, remotePort);
+  };
+  const scheduleHealthCheck = () => {
+    if (stopping || healthTimer !== null) return;
+    healthTimer = setTimeout(() => void healthCheck(), healthIntervalMs);
+  };
+  const healthCheck = async () => {
+    healthTimer = null;
     if (stopping) return;
-    emit({ t: "tunnel-down" });
+    if (reconnectActive) {
+      scheduleHealthCheck();
+      return;
+    }
+    if (await tcpListening(localPort)) {
+      scheduleHealthCheck();
+      return;
+    }
+    if (stopping || reconnectActive) return;
     void reconnect();
   };
   const reconnect = async () => {
+    if (reconnectActive || stopping) return;
+    reconnectActive = true;
+    const flapping = lastRestoredAt !== 0 && Date.now() - lastRestoredAt < STABLE_MS;
+    let announced = false;
+    const announce = () => {
+      announced = true;
+      emit({ t: "tunnel-down" });
+    };
+    const grace = flapping ? null : setTimeout(announce, downGraceMs);
+    if (flapping) announce();
     let delay = RECONNECT_INITIAL_MS;
-    while (!stopping) {
-      await sleep(delay);
-      if (stopping) return;
-      if (!await ssh.isAlive()) {
-        try {
-          await ssh.open();
-        } catch {
-          delay = Math.min(delay * 2, RECONNECT_MAX_MS);
-          continue;
+    let restored = false;
+    try {
+      while (!stopping) {
+        await sleep(delay);
+        if (stopping) break;
+        if (!await ssh.isAlive()) {
+          try {
+            await ssh.open();
+          } catch {
+            delay = Math.min(delay * 2, RECONNECT_MAX_MS);
+            continue;
+          }
         }
+        if (await spawnForward(localPort)) {
+          restored = true;
+          break;
+        }
+        const port = await findFreePort();
+        if (await spawnForward(port)) {
+          localPort = port;
+          portCbs.forEach((cb) => cb(port));
+          restored = true;
+          break;
+        }
+        delay = Math.min(delay * 2, RECONNECT_MAX_MS);
+        logger.warn(`tunnel to ${ssh.host} not back yet \u2014 retrying`);
       }
-      let port = localPort;
-      if (await spawnForward(port)) {
-        emit({ t: "tunnel-up" });
-        return;
-      }
-      state.child?.kill();
-      port = await findFreePort();
-      if (await spawnForward(port)) {
-        localPort = port;
-        portCbs.forEach((cb) => cb(port));
-        emit({ t: "tunnel-up" });
-        return;
-      }
-      state.child?.kill();
-      delay = Math.min(delay * 2, RECONNECT_MAX_MS);
-      logger.warn(`tunnel to ${ssh.host} not back yet \u2014 retrying`);
+    } finally {
+      if (grace !== null) clearTimeout(grace);
+      reconnectActive = false;
+    }
+    if (stopping) {
+      state.child?.kill("SIGTERM");
+      return;
+    }
+    if (restored) {
+      lastRestoredAt = Date.now();
+      if (announced) emit({ t: "tunnel-up" });
     }
+    scheduleHealthCheck();
   };
-  if (!await spawnForward(localPort)) {
-    state.child?.kill();
+  const initialReady = await spawnForward(localPort);
+  if (!initialReady) {
+    stopping = true;
     throw new CliError(
       "ssh_unreachable",
       `could not open a tunnel to ${ssh.host}:${remotePort}`,
       "is the daemon running on the host? try: puddle status " + ssh.host
     );
   }
+  scheduleHealthCheck();
   return {
     get localPort() {
       return localPort;
@@ -19848,19 +20155,76 @@ async function openTunnel(ssh, remotePort, opts = {}) {
     },
     close() {
       stopping = true;
-      return new Promise((resolve3) => {
-        const child = state.child;
-        if (child === null || child.exitCode !== null) return resolve3();
-        child.once("close", () => resolve3());
-        child.kill("SIGTERM");
-      });
+      if (healthTimer !== null) {
+        clearTimeout(healthTimer);
+        healthTimer = null;
+      }
+      const child = state.child;
+      state.child = null;
+      child?.kill("SIGTERM");
+      return ssh.cancelForward(localPort, remotePort);
     }
   };
 }
 
-// src/lib/transport/ssh.ts
+// src/lib/transport/local.ts
 import { spawn as spawn3 } from "node:child_process";
-import { mkdirSync } from "node:fs";
+import { copyFileSync, mkdirSync, readFileSync as readFileSync3 } from "node:fs";
+import { dirname as dirname3 } from "node:path";
+var LocalTransport = class {
+  kind = "local";
+  label = "this machine";
+  exec(command, opts = {}) {
+    return new Promise((resolve3) => {
+      const child = spawn3("sh", ["-c", command], { stdio: ["pipe", "pipe", "pipe"] });
+      let stdout = "";
+      let stderr = "";
+      let timer;
+      if (opts.timeoutMs !== void 0) {
+        timer = setTimeout(() => child.kill("SIGKILL"), opts.timeoutMs);
+        timer.unref();
+      }
+      child.stdout.on("data", (chunk) => {
+        const text = chunk.toString();
+        stdout += text;
+        opts.onStdout?.(text);
+      });
+      child.stderr.on("data", (chunk) => stderr += chunk.toString());
+      child.on("error", (err) => {
+        if (timer) clearTimeout(timer);
+        resolve3({ code: -1, stdout, stderr: stderr + String(err) });
+      });
+      child.on("close", (code) => {
+        if (timer) clearTimeout(timer);
+        resolve3({ code: code ?? -1, stdout, stderr });
+      });
+      if (opts.stdin !== void 0) child.stdin.end(opts.stdin);
+      else child.stdin.end();
+    });
+  }
+  readFile(path) {
+    try {
+      return Promise.resolve(readFileSync3(expandHome(path), "utf8"));
+    } catch {
+      return Promise.resolve(null);
+    }
+  }
+  copyTo(localPath, destPath) {
+    const dest = expandHome(destPath);
+    mkdirSync(dirname3(dest), { recursive: true });
+    copyFileSync(localPath, dest);
+    return Promise.resolve();
+  }
+  dispose() {
+  }
+};
+function expandHome(path) {
+  return path.startsWith('"${PUDDLE_HOME:-$HOME/.puddle}"') ? clientHome() + path.slice('"${PUDDLE_HOME:-$HOME/.puddle}"'.length) : path;
+}
+
+// src/lib/transport/ssh.ts
+import { spawn as spawn4 } from "node:child_process";
+import { mkdirSync as mkdirSync2 } from "node:fs";
 init_types();
 var SshTransport = class {
   constructor(host, opts = {}) {
@@ -19873,7 +20237,7 @@ var SshTransport = class {
       this.controlArgs = [];
     } else {
       const home = clientHome();
-      mkdirSync(home, { recursive: true });
+      mkdirSync2(home, { recursive: true });
       this.controlArgs = [
         "-o",
         "ControlMaster=auto",
@@ -19885,18 +20249,20 @@ var SshTransport = class {
         "ControlPersist=10m"
       ];
     }
+    this.keepaliveArgs = ["-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=3"];
   }
   kind = "ssh";
   label;
   ssh;
   scp;
   controlArgs;
+  keepaliveArgs;
   get hasControlMaster() {
     return this.controlArgs.length > 0;
   }
   /** Argv prefix every ssh/scp spawn shares. */
   args(...rest) {
-    return [...this.controlArgs, ...rest];
+    return [...this.controlArgs, ...this.keepaliveArgs, ...rest];
   }
   /**
    * Open the master interactively — ssh's own prompts go straight to the
@@ -19904,7 +20270,7 @@ var SshTransport = class {
    */
   open() {
     return new Promise((resolve3, reject) => {
-      const child = spawn3(this.ssh, this.args(this.host, "true"), { stdio: "inherit" });
+      const child = spawn4(this.ssh, this.args(this.host, "true"), { stdio: "inherit" });
       child.on(
         "error",
         (err) => reject(new CliError("ssh_unreachable", `could not run ${this.ssh}: ${err.message}`))
@@ -19927,14 +20293,33 @@ var SshTransport = class {
   isAlive() {
     if (!this.hasControlMaster) return Promise.resolve(true);
     return new Promise((resolve3) => {
-      const child = spawn3(this.ssh, this.args("-O", "check", this.host), { stdio: "ignore" });
+      const child = spawn4(this.ssh, this.args("-O", "check", this.host), { stdio: "ignore" });
       child.on("error", () => resolve3(false));
       child.on("close", (code) => resolve3(code === 0));
     });
   }
+  /**
+   * Best-effort removal of a multiplexed local forward (`-O cancel`). A
+   * non-OpenSSH server (Tailscale SSH) attaches the `-L` to the master and it
+   * outlives the spawning client — killing that client does not remove it, so
+   * the forward must be cancelled explicitly or the local port stays forwarded
+   * until the master lapses. A no-op (and unnecessary) without a master, where
+   * the forward dies with its own ssh process.
+   */
+  cancelForward(localPort, remotePort) {
+    if (!this.hasControlMaster) return Promise.resolve();
+    return new Promise((resolve3) => {
+      const spec = `${localPort}:127.0.0.1:${remotePort}`;
+      const child = spawn4(this.ssh, this.args("-O", "cancel", "-L", spec, this.host), {
+        stdio: "ignore"
+      });
+      child.on("error", () => resolve3());
+      child.on("close", () => resolve3());
+    });
+  }
   exec(command, opts = {}) {
     return new Promise((resolve3) => {
-      const child = spawn3(this.ssh, this.args(this.host, "--", `sh -c ${shellQuote(command)}`), {
+      const child = spawn4(this.ssh, this.args(this.host, "--", `sh -c ${shellQuote(command)}`), {
         stdio: ["pipe", "pipe", "pipe"]
       });
       let stdout = "";
@@ -19969,7 +20354,7 @@ var SshTransport = class {
   async copyTo(localPath, destPath) {
     await this.exec(`mkdir -p $(dirname ${destPath})`, { timeoutMs: 15e3 });
     await new Promise((resolve3, reject) => {
-      const child = spawn3(this.scp, [...this.controlArgs, localPath, `${this.host}:${destPath}`], {
+      const child = spawn4(this.scp, [...this.controlArgs, localPath, `${this.host}:${destPath}`], {
         stdio: ["ignore", "ignore", "inherit"]
       });
       child.on("error", reject);
@@ -20005,7 +20390,11 @@ async function connectRemote(opts) {
   const bootstrap = { tarball: opts.tarball, logger };
   const endpoint = await ensureDaemon(ssh, bootstrap);
   const remotePort = opts.remotePort ?? endpoint.port;
-  const tunnel = await openTunnel(ssh, remotePort, { sshBinary: opts.sshBinary, logger });
+  const tunnel = await openTunnel(ssh, remotePort, {
+    sshBinary: opts.sshBinary,
+    logger,
+    ready: (localPort) => waitForHttp(`http://127.0.0.1:${localPort}/api/version`, 8e3)
+  });
   const client = new DaemonClient(tunnel.localPort, endpoint.token);
   tunnel.onPortChange((port) => client.setPort(port));
   const daemon = await runHandshake({
@@ -20014,10 +20403,12 @@ async function connectRemote(opts) {
     upgradeDaemon: makeUpgrader(ssh, client, bootstrap),
     logger
   });
+  const avoidPort = await readDaemonPort(new LocalTransport());
   const ui = await startUiServer({
     assetsDir: opts.assetsDir,
     port: opts.port,
     strictPort: opts.port !== void 0,
+    avoidPort,
     target: { host: "127.0.0.1", port: tunnel.localPort }
   });
   tunnel.onPortChange((port) => ui.setTarget({ host: "127.0.0.1", port }));
@@ -20030,6 +20421,7 @@ async function connectRemote(opts) {
   return {
     origin: ui.origin,
     browserUrl: `${ui.origin}/?host=${encodeURIComponent(opts.host)}#token=${endpoint.token}`,
+    nonce: ui.nonce,
     daemon,
     onEvent(cb) {
       eventCbs.add(cb);
@@ -20066,59 +20458,77 @@ async function showLogs(transport, opts) {
   await transport.exec(command, { onStdout: opts.write });
 }
 
-// src/lib/transport/local.ts
-import { spawn as spawn4 } from "node:child_process";
-import { copyFileSync, mkdirSync as mkdirSync2, readFileSync as readFileSync3 } from "node:fs";
-import { dirname as dirname3 } from "node:path";
-var LocalTransport = class {
-  kind = "local";
-  label = "this machine";
-  exec(command, opts = {}) {
-    return new Promise((resolve3) => {
-      const child = spawn4("sh", ["-c", command], { stdio: ["pipe", "pipe", "pipe"] });
-      let stdout = "";
-      let stderr = "";
-      let timer;
-      if (opts.timeoutMs !== void 0) {
-        timer = setTimeout(() => child.kill("SIGKILL"), opts.timeoutMs);
-        timer.unref();
-      }
-      child.stdout.on("data", (chunk) => {
-        const text = chunk.toString();
-        stdout += text;
-        opts.onStdout?.(text);
-      });
-      child.stderr.on("data", (chunk) => stderr += chunk.toString());
-      child.on("error", (err) => {
-        if (timer) clearTimeout(timer);
-        resolve3({ code: -1, stdout, stderr: stderr + String(err) });
-      });
-      child.on("close", (code) => {
-        if (timer) clearTimeout(timer);
-        resolve3({ code: code ?? -1, stdout, stderr });
-      });
-      if (opts.stdin !== void 0) child.stdin.end(opts.stdin);
-      else child.stdin.end();
-    });
+// src/lib/registry.ts
+import { mkdirSync as mkdirSync3, readdirSync, readFileSync as readFileSync4, rmSync, writeFileSync } from "node:fs";
+import { join as join5 } from "node:path";
+function cockpitsDir(env) {
+  return join5(clientHome(env), "cockpits");
+}
+function slug(target) {
+  return target.replace(/[^A-Za-z0-9@._-]/g, "_");
+}
+function cockpitRecordPath(target) {
+  return join5(cockpitsDir(), `${slug(target)}.json`);
+}
+function cockpitLogPath(target) {
+  return join5(clientHome(), "logs", `cockpit-${slug(target)}.log`);
+}
+function writeCockpitRecord(record2) {
+  mkdirSync3(cockpitsDir(), { recursive: true, mode: 448 });
+  writeFileSync(cockpitRecordPath(record2.target), JSON.stringify(record2, null, 2) + "\n", {
+    mode: 384
+  });
+}
+function readCockpitRecord(target) {
+  try {
+    return JSON.parse(readFileSync4(cockpitRecordPath(target), "utf8"));
+  } catch {
+    return null;
   }
-  readFile(path) {
+}
+function removeCockpitRecord(target) {
+  rmSync(cockpitRecordPath(target), { force: true });
+}
+function listCockpitRecords() {
+  let names;
+  try {
+    names = readdirSync(cockpitsDir());
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
     try {
-      return Promise.resolve(readFileSync3(expandHome(path), "utf8"));
+      records.push(JSON.parse(readFileSync4(join5(cockpitsDir(), name), "utf8")));
     } catch {
-      return Promise.resolve(null);
     }
   }
-  copyTo(localPath, destPath) {
-    const dest = expandHome(destPath);
-    mkdirSync2(dirname3(dest), { recursive: true });
-    copyFileSync(localPath, dest);
-    return Promise.resolve();
+  return records.sort((a, b) => a.target.localeCompare(b.target));
+}
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
   }
-  dispose() {
+}
+async function checkCockpit(record2) {
+  if (!isPidAlive(record2.pid)) return "dead";
+  if (record2.status === "starting") return "starting";
+  if (record2.status !== "ready" || record2.origin === void 0 || record2.nonce === void 0) {
+    return "unverified";
+  }
+  try {
+    const res = await fetch(`${record2.origin}/`, {
+      method: "HEAD",
+      signal: AbortSignal.timeout(1500)
+    });
+    return res.headers.get("x-puddle-cockpit") === record2.nonce ? "running" : "unverified";
+  } catch {
+    return "unverified";
   }
-};
-function expandHome(path) {
-  return path.startsWith('"${PUDDLE_HOME:-$HOME/.puddle}"') ? clientHome() + path.slice('"${PUDDLE_HOME:-$HOME/.puddle}"'.length) : path;
 }
 
 // src/lib/start.ts
@@ -20139,12 +20549,15 @@ async function startLocal(opts) {
     assetsDir: opts.assetsDir,
     port: opts.port,
     strictPort: opts.port !== void 0,
+    avoidPort: endpoint.port,
+    // never squat the daemon's own port
     target: { host: "127.0.0.1", port: endpoint.port }
   });
   const eventCbs = /* @__PURE__ */ new Set();
   return {
     origin: ui.origin,
     browserUrl: `${ui.origin}/#token=${endpoint.token}`,
+    nonce: ui.nonce,
     daemon,
     onEvent(cb) {
       eventCbs.add(cb);
@@ -20199,6 +20612,129 @@ async function upgradeDaemon(transport, opts = {}) {
   return { from, to: opts.version ?? pinnedDaemonVersion(), liveSessions };
 }
 
+// src/cli/detach.ts
+import { spawn as spawn5 } from "node:child_process";
+import { closeSync, mkdirSync as mkdirSync4, openSync, readFileSync as readFileSync5 } from "node:fs";
+import { dirname as dirname4 } from "node:path";
+init_types();
+var COCKPIT_CHILD_ENV = "PUDDLE_COCKPIT_CHILD";
+var READY_TIMEOUT_MS = 3e5;
+function isCockpitChild(env = process.env) {
+  return env[COCKPIT_CHILD_ENV] === "1";
+}
+function killHint(target) {
+  return target === "local" ? "stop it with: puddle kill" : `stop it with: puddle kill ${target}`;
+}
+async function launchDetached(opts) {
+  const { target, logger } = opts;
+  const existing = readCockpitRecord(target);
+  if (existing !== null) {
+    const liveness = await checkCockpit(existing);
+    if (liveness === "running") {
+      logger.info(`a cockpit for ${target} is already running at ${existing.origin ?? "?"}`);
+      if (existing.browserUrl !== void 0) {
+        if (!opts.noBrowser) openBrowser(existing.browserUrl);
+        logger.info(`open: ${existing.browserUrl}`);
+      }
+      logger.info(killHint(target));
+      return 0;
+    }
+    if (liveness === "starting") {
+      logger.info(
+        `a cockpit for ${target} is already starting (pid ${existing.pid}) \u2014 puddle list to watch it`
+      );
+      return 0;
+    }
+    if (liveness === "unverified") {
+      throw new CliError(
+        "already_running",
+        `something holds the cockpit record for ${target} (pid ${existing.pid}) but did not answer at ${existing.origin ?? "its recorded origin"}`,
+        `if it is defunct: puddle kill ${target === "local" ? "local" : target}`
+      );
+    }
+    removeCockpitRecord(target);
+  }
+  if (target !== "local") await new SshTransport(target).open();
+  const logFile = cockpitLogPath(target);
+  mkdirSync4(dirname4(logFile), { recursive: true });
+  const fd = openSync(logFile, "w");
+  const child = spawn5(process.execPath, [process.argv[1] ?? "", ...process.argv.slice(2)], {
+    detached: true,
+    stdio: ["ignore", fd, fd],
+    env: { ...process.env, [COCKPIT_CHILD_ENV]: "1" }
+  });
+  closeSync(fd);
+  child.unref();
+  if (child.pid === void 0) {
+    throw new CliError("cockpit_launch_failed", "could not spawn the background cockpit process");
+  }
+  logger.info(`starting the cockpit for ${target} in the background\u2026`);
+  const record2 = await followStartup(target, child.pid, logFile);
+  if (record2 === null || record2.status !== "ready") {
+    if (record2?.status === "error") {
+      logger.warn(record2.message ?? "the cockpit failed to start");
+      if (record2.hint !== void 0) logger.info(`  hint: ${record2.hint}`);
+    } else {
+      logger.warn(`the cockpit did not report ready \u2014 its log: ${logFile}`);
+    }
+    logger.info("  (a run that stays on this terminal: add --foreground)");
+    const current = readCockpitRecord(target);
+    if (current !== null && current.pid === child.pid) removeCockpitRecord(target);
+    return 1;
+  }
+  const arrow = target === "local" ? "" : ` \u2192 ${target}`;
+  logger.info(`puddle cockpit at ${record2.origin ?? "?"}${arrow} \u2014 running in the background`);
+  if (record2.browserUrl !== void 0) {
+    if (!opts.noBrowser) openBrowser(record2.browserUrl);
+    logger.info(`open: ${record2.browserUrl}`);
+  }
+  logger.info(killHint(target));
+  return 0;
+}
+async function followStartup(target, childPid, logFile) {
+  let offset = 0;
+  const relay = () => {
+    try {
+      const buf = readFileSync5(logFile);
+      if (buf.length > offset) {
+        process.stderr.write(buf.subarray(offset));
+        offset = buf.length;
+      }
+    } catch {
+    }
+  };
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    relay();
+    const record2 = readCockpitRecord(target);
+    if (record2 !== null && record2.pid === childPid && record2.status !== "starting") return record2;
+    if (!isPidAlive(childPid)) {
+      relay();
+      const last2 = readCockpitRecord(target);
+      return last2 !== null && last2.pid === childPid ? last2 : null;
+    }
+    await sleep(200);
+  }
+  const last = readCockpitRecord(target);
+  return last !== null && last.pid === childPid ? last : null;
+}
+async function terminateCockpit(record2) {
+  try {
+    process.kill(record2.pid, "SIGTERM");
+  } catch {
+  }
+  const deadline = Date.now() + 5e3;
+  while (Date.now() < deadline && isPidAlive(record2.pid)) await sleep(100);
+  if (isPidAlive(record2.pid)) {
+    try {
+      process.kill(record2.pid, "SIGKILL");
+    } catch {
+    }
+  }
+  const current = readCockpitRecord(record2.target);
+  if (current === null || current.pid === record2.pid) removeCockpitRecord(record2.target);
+}
+
 // src/cli/output.ts
 function terminalLogger() {
   return {
@@ -20212,12 +20748,24 @@ function terminalLogger() {
     }
   };
 }
+function timestampedLogger() {
+  const line = (message) => `${(/* @__PURE__ */ new Date()).toISOString()} ${message}
+`;
+  return {
+    info(message) {
+      process.stderr.write(line(message));
+    },
+    warn(message) {
+      process.stderr.write(line(`puddle: ${message}`));
+    }
+  };
+}
 
 // src/cli/run.ts
 function assetsDir() {
-  const here = dirname4(fileURLToPath3(import.meta.url));
-  for (const candidate of [join5(here, "public"), join5(here, "..", "..", "dist", "public")]) {
-    if (existsSync3(join5(candidate, "index.html"))) return candidate;
+  const here = dirname5(fileURLToPath3(import.meta.url));
+  for (const candidate of [join6(here, "public"), join6(here, "..", "..", "dist", "public")]) {
+    if (existsSync3(join6(candidate, "index.html"))) return candidate;
   }
   throw new CliError(
     "not_installed",
@@ -20240,7 +20788,9 @@ async function openTarget(host) {
   let port = daemonPort;
   let tunnel = null;
   if (transport instanceof SshTransport) {
-    tunnel = await openTunnel(transport, daemonPort);
+    tunnel = await openTunnel(transport, daemonPort, {
+      ready: (localPort) => waitForHttp(`http://127.0.0.1:${localPort}/api/version`, 8e3)
+    });
     port = tunnel.localPort;
   }
   return {
@@ -20280,28 +20830,79 @@ async function run(command) {
       process.stdout.write(`puddle ${cliVersion()}
 `);
       return 0;
-    case "start": {
-      const cockpit = await startLocal({ ...command, assetsDir: assetsDir(), logger });
-      logger.info(`puddle cockpit at ${cockpit.origin} (daemon ${cockpit.daemon.version})`);
-      if (!command.noBrowser) openBrowser(cockpit.browserUrl);
-      logger.info(`open: ${cockpit.browserUrl}`);
-      await runUntilInterrupted(
-        cockpit.stop,
-        "cockpit closed \u2014 sessions keep running on this machine"
+    case "start":
+    case "connect": {
+      const target = command.cmd === "connect" ? command.host : "local";
+      if (!command.foreground && !isCockpitChild()) {
+        return launchDetached({ target, noBrowser: command.noBrowser, logger });
+      }
+      return runCockpit(command, target, logger);
+    }
+    case "list": {
+      const rows = [];
+      for (const record2 of listCockpitRecords()) {
+        const liveness = await checkCockpit(record2);
+        if (liveness === "dead") {
+          removeCockpitRecord(record2.target);
+          continue;
+        }
+        rows.push({ record: record2, liveness });
+      }
+      if (rows.length === 0) {
+        process.stdout.write("no cockpits are running\n");
+        return 0;
+      }
+      process.stdout.write(
+        `${pad("TARGET", 26)} ${pad("STATUS", 9)} ${pad("PID", 7)} ${pad("UI", 24)} STARTED
+`
       );
+      for (const { record: record2, liveness } of rows) {
+        process.stdout.write(
+          `${pad(record2.target, 26)} ${pad(liveness, 9)} ${pad(String(record2.pid), 7)} ${pad(record2.origin ?? "\u2014", 24)} ${record2.startedAt}
+`
+        );
+      }
       return 0;
     }
-    case "connect": {
-      const cockpit = await connectRemote({ ...command, assetsDir: assetsDir(), logger });
-      logger.info(
-        `puddle cockpit at ${cockpit.origin} \u2192 ${command.host} (daemon ${cockpit.daemon.version})`
-      );
-      if (!command.noBrowser) openBrowser(cockpit.browserUrl);
-      logger.info(`open: ${cockpit.browserUrl}`);
-      await runUntilInterrupted(
-        cockpit.stop,
-        `cockpit closed \u2014 sessions keep running on ${command.host}`
-      );
+    case "kill": {
+      const live = [];
+      for (const record2 of listCockpitRecords()) {
+        if (await checkCockpit(record2) === "dead") removeCockpitRecord(record2.target);
+        else live.push(record2);
+      }
+      let victims;
+      if (command.all) {
+        if (live.length === 0) {
+          logger.info("no cockpits are running");
+          return 0;
+        }
+        victims = live;
+      } else if (command.target !== void 0) {
+        const found = live.find((r) => r.target === command.target);
+        if (found === void 0) {
+          throw new CliError(
+            "no_cockpit",
+            `no cockpit is running for ${command.target}`,
+            live.length > 0 ? `running: ${live.map((r) => r.target).join(", ")}` : "see: puddle list"
+          );
+        }
+        victims = [found];
+      } else {
+        if (live.length === 0) throw new CliError("no_cockpit", "no cockpits are running");
+        if (live.length > 1) {
+          throw new CliError(
+            "bad_arguments",
+            "several cockpits are running \u2014 name the one to kill",
+            `puddle kill <${live.map((r) => r.target).join(" | ")}>  (or --all)`
+          );
+        }
+        victims = live;
+      }
+      for (const victim of victims) {
+        await terminateCockpit(victim);
+        const where = victim.target === "local" ? "this machine" : victim.target;
+        logger.info(`stopped the cockpit for ${victim.target} \u2014 sessions keep running on ${where}`);
+      }
       return 0;
     }
     case "status": {
@@ -20400,6 +21001,65 @@ async function run(command) {
     }
   }
 }
+async function runCockpit(command, target, terminal) {
+  const detached = isCockpitChild();
+  const logger = detached ? timestampedLogger() : terminal;
+  const existing = readCockpitRecord(target);
+  if (existing !== null && existing.pid !== process.pid) {
+    if (await checkCockpit(existing) !== "dead") {
+      throw new CliError(
+        "already_running",
+        `a cockpit for ${target} is already running at ${existing.origin ?? `pid ${existing.pid}`}`,
+        killHint(target).replace("stop it", "stop it first")
+      );
+    }
+    removeCockpitRecord(target);
+  }
+  const base = {
+    target,
+    pid: process.pid,
+    status: "starting",
+    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    cliVersion: cliVersion(),
+    ...detached ? { logFile: cockpitLogPath(target) } : {}
+  };
+  writeCockpitRecord(base);
+  let cockpit;
+  try {
+    cockpit = command.cmd === "start" ? await startLocal({ ...command, assetsDir: assetsDir(), logger }) : await connectRemote({ ...command, assetsDir: assetsDir(), logger });
+  } catch (err) {
+    if (err instanceof CliError) {
+      writeCockpitRecord({
+        ...base,
+        status: "error",
+        message: err.message,
+        ...err.hint !== void 0 ? { hint: err.hint } : {}
+      });
+    } else {
+      removeCockpitRecord(target);
+    }
+    throw err;
+  }
+  writeCockpitRecord({
+    ...base,
+    status: "ready",
+    origin: cockpit.origin,
+    browserUrl: cockpit.browserUrl,
+    nonce: cockpit.nonce
+  });
+  const arrow = command.cmd === "connect" ? ` \u2192 ${command.host}` : "";
+  logger.info(`puddle cockpit at ${cockpit.origin}${arrow} (daemon ${cockpit.daemon.version})`);
+  if (!detached) {
+    if (!command.noBrowser) openBrowser(cockpit.browserUrl);
+    logger.info(`open: ${cockpit.browserUrl}`);
+  }
+  const where = command.cmd === "start" ? "this machine" : command.host;
+  await runUntilInterrupted(async () => {
+    await cockpit.stop();
+    removeCockpitRecord(target);
+  }, `cockpit closed \u2014 sessions keep running on ${where}`);
+  return 0;
+}
 function pad(text, width) {
   return text.length >= width ? text.slice(0, width - 1) + "\u2026" : text.padEnd(width);
 }