package main

import (
	"bufio"
	"context"
	"crypto/tls"
	"flag"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"os/exec"
	"path/filepath"
	"regexp"
	"sort"
	"strings"
	"syscall"
	"time"

	"github.com/benbjohnson/litestream"
	"unicode"
	"unicode/utf8"
)

// The control subcommands automate what an operator would otherwise do by hand to
// stand up an instance behind the router: mint the admin token, write the unit's
// EnvironmentFile, start the instance, register + reload the route. See
// docs/instance-router.md.

// Instance paths are fixed by the systemd units (deploy/systemd/lchat@.service),
// so the control commands use these rather than per-invocation flags that would
// silently diverge from where the instance actually listens + stores. Vars with
// env overrides (cf. optDir) so tests can point them at temp dirs.
var (
	instanceDataDir   = envOr("LCHAT_DATA_DIR", "/data")        // <host>.db + <host>.env live here
	instanceSocketDir = envOr("LCHAT_SOCKET_DIR", "/run/lchat") // <host>.sock lives here
)

// routerHTTPSAddr is where the local router serves TLS — prewarmCert dials it to
// trigger cert issuance for a new host. Loopback by default (the router binds
// :443 on the same box); overridable if the router listens elsewhere.
var routerHTTPSAddr = envOr("LCHAT_ROUTER_HTTPS_ADDR", "127.0.0.1:443")

var hostnameRe = regexp.MustCompile(`^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$`)

// validHost reports whether h is a plausible DNS hostname. It's strict because
// <host> becomes a filename, a systemd instance name, and a unix socket path.
func validHost(h string) bool {
	return len(h) > 0 && len(h) <= 253 && hostnameRe.MatchString(h)
}

// checkSocketLen guards the unix sun_path limit (104 bytes on darwin/BSD, 108 on
// Linux — stay under the smaller so a path is portable). A too-long path fails at
// bind() with a cryptic error, so catch it early.
func checkSocketLen(path string) error {
	if len(path) >= 104 {
		return fmt.Errorf("socket path %q is too long (%d bytes; unix limit ~104)", path, len(path))
	}
	return nil
}

func die(format string, a ...any) {
	fmt.Fprintf(os.Stderr, format+"\n", a...)
	os.Exit(1)
}

// reorderFlagsFirst moves positional args after all flags so the stdlib flag
// parser (which stops at the first positional) still sees every flag — letting
// `add-instance <host> --flag v` work as naturally as `--flag v <host>`.
func reorderFlagsFirst(fs *flag.FlagSet, args []string) []string {
	var flags, positional []string
	for i := 0; i < len(args); i++ {
		a := args[i]
		if a == "--" {
			positional = append(positional, args[i+1:]...)
			break
		}
		if len(a) > 1 && a[0] == '-' {
			flags = append(flags, a)
			name := strings.TrimLeft(a, "-")
			if strings.IndexByte(name, '=') >= 0 {
				continue // --flag=value carries its own value
			}
			f := fs.Lookup(name)
			if f == nil {
				continue // unknown flag; let Parse report it
			}
			if bf, ok := f.Value.(interface{ IsBoolFlag() bool }); ok && bf.IsBoolFlag() {
				continue // bool flag takes no value
			}
			// Pull the value along, unless the next token is itself a flag (a
			// missing value) — let Parse report that rather than silently eating it.
			if i+1 < len(args) && !(len(args[i+1]) > 1 && args[i+1][0] == '-') {
				i++
				flags = append(flags, args[i])
			}
			continue
		}
		positional = append(positional, a)
	}
	return append(flags, positional...)
}

// Sentinel errors so callers (the CLI, controld) can map failures to stable
// outcomes without parsing message strings.
var (
	errHostExists  = fmt.Errorf("host already exists")
	errInvalidHost = fmt.Errorf("invalid host")
)

// addInstanceOpts parameterizes one instance creation. Host is required; an
// empty AdminToken mints a fresh one (a non-empty one imports an existing token,
// the migration path).
type addInstanceOpts struct {
	Host           string
	AdminToken     string
	AppStoreURL    string
	HomeOrigin     string
	PushRelayURL   string
	PushRelayToken string
	// Entitlement mirrors the cloud ledger's plan flag ("free"/"paid") into the
	// instance env (LCHAT_ENTITLEMENT) so its UI can gate billing affordances —
	// the space menu's Upgrade. Empty for operator-created instances, which have
	// no billing surface and show nothing.
	Entitlement string
	// GroupName seeds the space's display name (LCHAT_GROUP_NAME → the instance
	// names itself at first boot; main.go applySeededName). The create flow asks
	// for the name up front, so a provisioned space greets its admin by name
	// instead of as "lchat". Seed-only: an already-named space ignores it.
	GroupName  string
	HomeRegion string // geo seam (#550 Part 7): "" = the single implicit region
	Provider   string // co-op seam (#550 Part 10): "" = the single implicit provider
	// Hibernate registers the instance as activator-managed (#550 Part 4 v2):
	// no systemd unit is created — the router wakes it on first request. Needs
	// the router running with LCHAT_HIBERNATE_BUCKET, or the host never answers.
	Hibernate bool
	// Canary flags the instance as a throwaway test host (registry.go: Route.Canary).
	Canary bool
	// Replication is the durability class on the activator's S3 replica
	// (registry.go: stream/batched/daily; "" = stream) — set at birth so a
	// provisioned space starts on its plan's rung instead of the most
	// expensive one. Inert unless Hibernate.
	Replication string
	UnitTmpl    string // default "lchat@"
	RouterUnit  string // default "lchat-router"
}

// sanitizeGroupName makes an untrusted display name safe to carry in the
// KEY=value env file writeEnvFile emits: control characters (newlines would
// inject env lines) are dropped, whitespace trimmed, and length capped at 60
// bytes on a rune boundary — the same cap the instance's own rename enforces.
func sanitizeGroupName(name string) string {
	name = strings.Map(func(r rune) rune {
		if unicode.IsControl(r) {
			return -1
		}
		return r
	}, name)
	name = strings.TrimSpace(name)
	if len(name) > 60 {
		cut := 60
		for cut > 0 && !utf8.RuneStart(name[cut]) {
			cut--
		}
		name = strings.TrimSpace(name[:cut])
	}
	return name
}

// addInstanceResult is what a successful creation yields. SetupLink may be empty
// with SetupErr set: the invite mint is best-effort (the admin link still
// bootstraps the instance), matching the CLI's long-standing behaviour.
type addInstanceResult struct {
	Host       string
	AdminToken string
	SetupLink  string
	SetupErr   error
}

// addInstance is the shared creation core behind `lchat add-instance` and the
// control daemon (controld.go). It is deliberately two named steps — register
// (the row) then materialize (the machinery) — because the planet-scale plan
// (#550 Part 4 v2 / Part 5) eventually makes "create a space" *just* register:
// a registry row plus a storage prefix, microseconds and uncapped, with
// materialization deferred to the first wake (hibernation kills the day-one
// blip). Today the two always run back to back and the caller's capacity cap
// (controld.atCapacity) guards the pair, exactly as it did before the split.
func addInstance(reg *Registry, opts addInstanceOpts) (*addInstanceResult, error) {
	opts.GroupName = sanitizeGroupName(opts.GroupName)
	route, token, err := registerInstance(reg, opts)
	if err != nil {
		return nil, err
	}
	return materializeInstance(reg, route, token, opts)
}

// registerInstance records that the space exists: validate the host, mint (or
// import) the admin token, and write the registry row (status "creating").
// Pure metadata — no env file, no unit, no process — so it never consumes box
// capacity. Placement (HomeRegion/Provider) is recorded here because it's a
// property of the space, not of any one materialization.
func registerInstance(reg *Registry, opts addInstanceOpts) (Route, string, error) {
	host := strings.ToLower(strings.TrimSpace(opts.Host))
	if !validHost(host) {
		return Route{}, "", fmt.Errorf("%w: %q (want a hostname like chat.example.com)", errInvalidHost, host)
	}
	socket := filepath.Join(instanceSocketDir, host+".sock")
	if err := checkSocketLen(socket); err != nil {
		return Route{}, "", fmt.Errorf("%w: %v", errInvalidHost, err)
	}

	if existing, err := reg.get(host); err != nil {
		return Route{}, "", err
	} else if existing != nil && existing.Status == "ready" {
		return Route{}, "", fmt.Errorf("%w: %q", errHostExists, host)
	}
	// A prior failed/creating attempt is overwritten on retry.

	// An imported AdminToken (migration): the instance's boot rewrites
	// admin_token_hash from the env, so passing the old token over a pre-placed
	// migrated DB leaves the hash — and every saved admin link — intact.
	token := opts.AdminToken
	if token == "" {
		var err error
		if token, err = randToken(); err != nil {
			return Route{}, "", fmt.Errorf("token: %v", err)
		}
	}

	if !validReplication(opts.Replication) {
		return Route{}, "", fmt.Errorf("unknown replication class %q (want %s, %s or %s)",
			opts.Replication, replicationStream, replicationBatched, replicationDaily)
	}

	route := Route{Host: host, Kind: "instance", Socket: socket,
		DBPath: filepath.Join(instanceDataDir, host+".db"), Status: "creating",
		AppStoreURL: opts.AppStoreURL, HomeOrigin: opts.HomeOrigin, PushRelayURL: opts.PushRelayURL,
		HomeRegion: opts.HomeRegion, Provider: opts.Provider, Hibernate: opts.Hibernate,
		Canary: opts.Canary, Replication: opts.Replication}
	if err := reg.upsert(route); err != nil {
		return Route{}, "", fmt.Errorf("register: %v", err)
	}
	return route, token, nil
}

// materializeInstance turns a registered row into a running instance: env file,
// staged binary + live symlink, systemd unit, health check, router reload,
// setup invite. This is the half that consumes real capacity (a process, a
// socket, disk), which is why the capacity cap conceptually belongs to it — and
// the seam exists so it can later run at first *wake* rather than at create
// (#550 Part 4 v2).
func materializeInstance(reg *Registry, route Route, token string, opts addInstanceOpts) (*addInstanceResult, error) {
	host := route.Host
	socket := route.Socket
	unitTmpl := opts.UnitTmpl
	if unitTmpl == "" {
		unitTmpl = "lchat@"
	}
	routerUnit := opts.RouterUnit
	if routerUnit == "" {
		routerUnit = "lchat-router"
	}

	// The instance stores only the token's hash, so this is the one chance to
	// capture the plaintext. Persist it (and per-instance config) to an
	// EnvironmentFile the unit reads — that keeps it recoverable via `admin-link`.
	env := instanceEnvMap(token, opts.AppStoreURL, opts.HomeOrigin,
		opts.PushRelayURL, opts.PushRelayToken, opts.Entitlement, opts.GroupName)
	envPath := filepath.Join(instanceDataDir, host+".env")
	if err := writeEnvFile(envPath, env); err != nil {
		return nil, fmt.Errorf("write env file: %v", err)
	}
	if route.Hibernate {
		// Systemd-managed instances never care who owns the env file — systemd
		// reads EnvironmentFile as root before dropping privileges. A hibernating
		// instance's env is read by the ROUTER at wake time, and the router runs
		// as the service user, so root-run add-instance must hand the file over
		// (found live: the canary's first wake died on permission denied).
		if err := matchOwner(envPath, instanceDataDir); err != nil {
			return nil, fmt.Errorf("env file ownership: %v", err)
		}
	}

	// The instance's unit execs /opt/lchat/live/<host>; stage the running control
	// binary and point that symlink at it, so ExecStart resolves on first start.
	// A fresh instance therefore runs whatever build the operator's `lchat` is.
	ver, err := ensureSelfStaged()
	if err != nil {
		return nil, fmt.Errorf("stage binary: %v", err)
	}
	if err := pointLive(host, ver); err != nil {
		return nil, fmt.Errorf("point live symlink: %v", err)
	}
	route.Version = ver

	// The systemd half — the ONLY part a hibernating instance skips. The split
	// is derived from what the activator's spawn (s3Backend.start) needs at
	// first wake: the env file above (the spawn layers /data/<host>.env over a
	// clean env, and the admin token's plaintext lives nowhere else — without
	// it the woken instance would mint its own token and every saved admin
	// link would be dead); the staged binary + live symlink above (the spawn
	// execs /opt/lchat/live/<host>, and staging here keeps the instance under
	// normal version management instead of self-healing onto the router's own
	// build); and the ready row + router reload below (or no request can ever
	// reach the host to wake it). What a hibernating instance must NOT have is
	// a unit holding the socket — the instance refuses to clobber a live
	// listener (listen() in main.go), so a running unit would turn every wake
	// into "socket already in use". No DB is created either: the first wake
	// finds no replica in S3 and boots fresh. And there's no health check here
	// because nothing runs yet — the public-readiness probe below is the first
	// request, and the wake it triggers is the health check.
	if !route.Hibernate {
		unit := unitTmpl + host
		if err := systemctl("enable", "--now", unit); err != nil {
			markInstanceFailed(reg, host, unit, "start: "+err.Error())
			return nil, fmt.Errorf("start %s: %v", unit, err)
		}
		if err := waitHealthy(socket, 15*time.Second); err != nil {
			markInstanceFailed(reg, host, unit, "health: "+err.Error())
			return nil, err
		}
	}

	route.Status = "ready"
	if err := reg.upsert(route); err != nil {
		return nil, fmt.Errorf("mark ready: %v", err)
	}
	if route.Hibernate {
		// Best-effort: give any live mesh peer this route before HRW could ever
		// place it there (meshreplicate.go). A no-op when the mesh is off or
		// this host is out of LCHAT_MESH_DOMAINS scope — self-hosters and
		// non-mesh boxes are unaffected. Never fails materialization: the
		// route and admin link stand regardless of replication's outcome.
		if hc, hcErr := hibernateConfigFromEnv(); hcErr != nil {
			log.Printf("mesh: skipping route replication for %s: %v", host, hcErr)
		} else {
			fanOutMeshRoute(hc, route, env)
		}
	}
	if err := systemctl("reload", routerUnit); err != nil {
		return nil, fmt.Errorf("reload %s: %v (route added; run: systemctl reload %s)", routerUnit, err, routerUnit)
	}

	// Confirm the space answers through the PUBLIC path (router → this instance)
	// before we hand back a setup link, so the moment a human clicks it they land
	// on a ready admin sign-on — never a mid-provision error. This also warms the
	// per-host TLS cert as a side effect (the handshake triggers autocert), so the
	// first visitor doesn't race on-demand issuance. Best-effort: on failure we
	// still return (the instance passed its own health check); the public path is
	// almost certainly up a beat later.
	//
	// For a hibernating instance this probe is also its FIRST WAKE: the request
	// makes the router's activator spawn the child, which binds the socket the
	// setup-invite mint below dials. If the wake never lands (e.g. the router
	// isn't running with LCHAT_HIBERNATE_BUCKET), the mint fails and we degrade
	// to the usual "setup link unavailable" path — the route and admin link
	// still stand.
	confirmPublicReady(host, routerHTTPSAddr)

	// The first-user setup link: claiming it makes you the instance's admin and
	// lands you in the chat view, where the Eleven setup conversation takes over.
	// Minting can only fail against an unhealthy instance (we just health-checked),
	// but if it does the admin link still bootstraps the old way.
	res := &addInstanceResult{Host: host, AdminToken: token}
	res.SetupLink, res.SetupErr = mintSetupInvite(socketClient(socket), "http://lchat", "https://"+host, token)
	if res.SetupErr != nil {
		// A hibernating instance may live behind the local socket in name only:
		// the mesh can place it on a peer box, where the readiness probe above
		// woke it — locally nothing listens, ever. Mint through the public path
		// instead (the same router hop the member will use), which follows the
		// mesh to wherever the instance actually runs; the replicated env means
		// it holds the same admin token. Non-mesh boxes just get a second local
		// try through the router, which is harmless.
		link, perr := mintPublicSetupInvite(host, token)
		if perr != nil {
			res.SetupErr = fmt.Errorf("socket: %v; public: %v", res.SetupErr, perr)
			res.SetupLink = ""
		} else {
			res.SetupLink, res.SetupErr = link, nil
		}
	}
	return res, nil
}

// mintPublicSetupInvite mints the setup link through the local router's public
// HTTPS front (SNI-pinned like confirmPublicReady, so the real route + cert
// are exercised) — the path that works no matter which mesh box the instance
// woke on. A var so the add-instance tests, which run no TLS router, can stub
// it alongside confirmPublicReady.
var mintPublicSetupInvite = func(host, adminToken string) (string, error) {
	client := &http.Client{
		Timeout: 15 * time.Second,
		Transport: &http.Transport{
			DialTLSContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
				return (&tls.Dialer{Config: &tls.Config{ServerName: host}}).DialContext(ctx, "tcp", routerHTTPSAddr)
			},
		},
	}
	return mintSetupInvite(client, "https://"+host, "https://"+host, adminToken)
}

// runAddInstance: `lchat add-instance <host>` — mint token + env file, start the
// instance unit, register the route, reload the router.
func runAddInstance(args []string) {
	fs := flag.NewFlagSet("add-instance", flag.ExitOnError)
	registryPath := fs.String("registry", envOr("LCHAT_REGISTRY", "/data/registry.db"), "router registry SQLite path")
	unitTmpl := fs.String("unit", envOr("LCHAT_UNIT", "lchat@"), "systemd instance unit template prefix")
	routerUnit := fs.String("router-unit", envOr("LCHAT_ROUTER_UNIT", "lchat-router"), "router systemd unit to reload")
	adminToken := fs.String("admin-token", "", "import: use this admin token instead of minting a new one (preserves saved admin links when migrating an instance whose DB is already in place)")
	appStoreURL := fs.String("app-store-url", "", "per-instance LCHAT_APP_STORE_URL")
	homeOrigin := fs.String("home-origin", "", "per-instance LCHAT_HOME_ORIGIN")
	groupName := fs.String("group-name", "", "seed the space's display name (LCHAT_GROUP_NAME; the instance names itself at first boot — an already-named space ignores it)")
	pushRelayURL := fs.String("push-relay-url", "", "per-instance LCHAT_PUSH_RELAY_URL")
	pushRelayToken := fs.String("push-relay-token", "", "per-instance LCHAT_PUSH_RELAY_TOKEN")
	homeRegion := fs.String("home-region", "", "placement region recorded as the instance's home_region (multi-edge, docs/multi-edge.md) — the mesh owns the space on a box whose LCHAT_MESH_REGION matches; empty = region-agnostic (today's behaviour)")
	hibernate := fs.Bool("hibernate", false, "register as activator-managed (no systemd unit; the router wakes it on demand — requires the router to run with LCHAT_HIBERNATE_BUCKET)")
	replication := fs.String("replication", "", "replication class on the activator's S3 replica: stream (default), batched, or daily — the per-plan durability ladder; inert without --hibernate")
	canary := fs.Bool("canary", false, "mark as a throwaway test instance (a per-session canary) — a deliberate signal, never inferred from the hostname; lets fleet ops and a future scoped reset treat it as disposable")
	_ = fs.Parse(reorderFlagsFirst(fs, args))

	reg, err := openRegistry(*registryPath)
	if err != nil {
		die("add-instance: open registry: %v", err)
	}
	res, err := addInstance(reg, addInstanceOpts{
		Host:           fs.Arg(0),
		AdminToken:     *adminToken,
		AppStoreURL:    *appStoreURL,
		HomeOrigin:     *homeOrigin,
		GroupName:      *groupName,
		PushRelayURL:   *pushRelayURL,
		PushRelayToken: *pushRelayToken,
		HomeRegion:     strings.TrimSpace(*homeRegion),
		Hibernate:      *hibernate,
		Canary:         *canary,
		Replication:    strings.ToLower(strings.TrimSpace(*replication)),
		UnitTmpl:       *unitTmpl,
		RouterUnit:     *routerUnit,
	})
	if err != nil {
		die("add-instance: %v", err)
	}

	fmt.Printf("added %s\n", res.Host)
	if *hibernate {
		fmt.Printf("  hibernating: no systemd unit — the router wakes it per request and sleeps it when idle\n")
	}
	if *canary {
		fmt.Printf("  canary: flagged as a throwaway test instance\n")
	}
	if res.SetupErr != nil {
		fmt.Printf("  (setup link unavailable: %v — mint later: lchat setup-invite %s)\n", res.SetupErr, res.Host)
	} else {
		fmt.Printf("  get started (one-time link, makes you the admin):\n  %s\n", res.SetupLink)
	}
	fmt.Printf("  admin token link: https://%s/admin#token=%s\n  (recover later: lchat admin-link %s / lchat setup-invite %s)\n", res.Host, res.AdminToken, res.Host, res.Host)
}

// runAddService: `lchat add-service <host> --socket <path>` — front an
// externally-managed backend (the home server, push relay, or a third party's).
// Unlike an instance, the router only proxies it; it doesn't start or supervise
// the process. See docs/instance-router.md.
func runAddService(args []string) {
	fs := flag.NewFlagSet("add-service", flag.ExitOnError)
	registryPath := fs.String("registry", envOr("LCHAT_REGISTRY", "/data/registry.db"), "router registry SQLite path")
	socket := fs.String("socket", "", "unix socket the service already listens on (required)")
	routerUnit := fs.String("router-unit", envOr("LCHAT_ROUTER_UNIT", "lchat-router"), "router systemd unit to reload")
	_ = fs.Parse(reorderFlagsFirst(fs, args))

	host := strings.ToLower(strings.TrimSpace(fs.Arg(0)))
	if !validHost(host) {
		die("add-service: invalid host %q", host)
	}
	if *socket == "" {
		die("add-service: --socket <path> is required (where the service listens)")
	}
	if err := checkSocketLen(*socket); err != nil {
		die("add-service: %v", err)
	}
	reg, err := openRegistry(*registryPath)
	if err != nil {
		die("add-service: open registry: %v", err)
	}
	if existing, err := reg.get(host); err != nil {
		die("add-service: %v", err)
	} else if existing != nil {
		die("add-service: host %q already exists (status %s)", host, existing.Status)
	}
	// The backend must already be up — the router only proxies it. Use a lax
	// reachability check (any HTTP response, redirects not followed): a service's
	// "/" may legitimately 3xx/4xx/5xx, unlike a messenger instance.
	if err := waitReachable(*socket, 10*time.Second); err != nil {
		die("add-service: %s not answering on %s: %v (start the service first)", host, *socket, err)
	}
	if err := reg.upsert(Route{Host: host, Kind: "service", Socket: *socket, Status: "ready"}); err != nil {
		die("add-service: register: %v", err)
	}
	if err := systemctl("reload", *routerUnit); err != nil {
		die("add-service: reload %s: %v (route added; run: systemctl reload %s)", *routerUnit, err, *routerUnit)
	}
	fmt.Printf("added service %s -> %s\n", host, *socket)
}

// errUnknownHost lets callers (controld) map "no such instance" to a 404.
var errUnknownHost = fmt.Errorf("unknown host")

// deleteInstance is the shared deprovisioning core behind the control daemon's
// DELETE (self-serve space deletion): stop the units, drop the route, reload the
// router, and ARCHIVE the instance's data — the DB/env move to
// /data/trash/<host>-<unix>/ rather than being destroyed, so an operator can
// still recover a space deleted in error until the trash is purged. The cert and
// live symlink are removed (both are re-creatable).
//
// A hibernating space's S3 replica (s3://<bucket>/<prefix>/<host>/) is
// deliberately NOT deleted here: controld holds no bucket credentials (only the
// router process does, and widening the root daemon's reach for this buys
// nothing), the prefix is opaque ciphertext of a DB whose authoritative copy
// just moved to trash, and the production bucket is versioned with a
// noncurrent-version expiry, so an orphaned prefix ages rather than grows.
// Reclaiming orphaned prefixes is deferred to the S3 lifecycle work — an
// offline sweep comparing bucket prefixes against the registry.
func deleteInstance(reg *Registry, host string, discard bool) error {
	host = strings.ToLower(strings.TrimSpace(host))
	if !validHost(host) {
		return fmt.Errorf("%w: %q", errInvalidHost, host)
	}
	rt, err := reg.get(host)
	if err != nil {
		return err
	}
	if rt == nil {
		return fmt.Errorf("%w: %q", errUnknownHost, host)
	}
	if rt.Kind != "instance" {
		return fmt.Errorf("%q is a %s route, not an instance", host, rt.Kind)
	}
	_ = systemctl("disable", "--now", "lchat-bot@"+host) // best-effort: a sidecar may not exist
	if rt.Hibernate {
		// Activator-managed: there is no lchat@ unit — stopping one is
		// best-effort only, covering a half-flipped host. If the child is
		// awake it's the ROUTER that puts it down: the route delete + reload
		// below make the reload-time reconcile (retireExcept, activator.go)
		// stop the child, take the final checkpoint, and release the S3 lease.
		_ = systemctl("disable", "--now", "lchat@"+host)
	} else if err := systemctl("disable", "--now", "lchat@"+host); err != nil {
		return fmt.Errorf("stop unit: %v", err)
	}
	if err := reg.delete(host); err != nil {
		return fmt.Errorf("deregister: %v", err)
	}
	if err := systemctl("reload", "lchat-router"); err != nil {
		return fmt.Errorf("reload router: %v", err)
	}
	// The row is authoritatively gone here — tell the mesh peers so a
	// destroyed space can't live on (or wake!) from a replicated copy
	// (#1346). Best-effort like creation fan-out; a missed peer reconciles at
	// the next mesh-seed --prune. No-op off-mesh.
	if hc, hcErr := hibernateConfigFromEnv(); hcErr == nil {
		fanOutMeshRouteDelete(hc, host)
	}
	if rt.Hibernate {
		// The retire is asynchronous inside the router process; wait (bounded)
		// for the child to release the socket so the archive renames below
		// don't race its final checkpoint. Instant in the common case — the
		// reaper's targets are asleep or never woken, so nothing listens.
		// Best-effort on timeout: open fds follow the renamed inode, so a
		// straggling checkpoint lands harmlessly inside the archive.
		_ = waitSocketQuiet(rt.Socket, deleteReleaseTimeout)
	}
	// Archive the data (never destroy it here — the trash dir is the safety
	// net) — except under discard, the demo tier's no-backups contract
	// (docs/demo-spaces.md): a demo's files are removed outright, blob dir
	// included, so nothing of a disclosed-24h space outlives it.
	// The litestream meta dir rides along: it describes the archived DB, and a
	// leftover would only confuse a future re-create of the same host (the wake
	// path clears a stale one, but don't rely on it).
	names := []string{host + ".db", host + ".db-wal", host + ".db-shm", host + ".db" + litestream.MetaDirSuffix, host + ".env", host + ".vapid"}
	if discard {
		for _, name := range append(names, host+"-blobs") {
			if err := os.RemoveAll(filepath.Join(instanceDataDir, name)); err != nil {
				return fmt.Errorf("discard %s: %v", name, err)
			}
		}
	} else {
		trash := filepath.Join(instanceDataDir, "trash", fmt.Sprintf("%s-%d", host, time.Now().Unix()))
		if err := os.MkdirAll(trash, 0o700); err != nil {
			return fmt.Errorf("trash dir: %v", err)
		}
		for _, name := range names {
			src := filepath.Join(instanceDataDir, name)
			if _, err := os.Stat(src); err == nil {
				if err := os.Rename(src, filepath.Join(trash, name)); err != nil {
					return fmt.Errorf("archive %s: %v", name, err)
				}
			}
		}
	}
	_ = os.Remove(filepath.Join(instanceDataDir, "acme", host)) // cert re-issues if ever needed
	_ = os.Remove(liveLink(host))
	return nil
}

// deleteReleaseTimeout bounds how long deleteInstance waits for the activator
// to release a hibernating instance's socket before archiving. A var so tests
// can shrink the (rare) still-listening path.
var deleteReleaseTimeout = 30 * time.Second

// runRemove: `lchat remove <host>` — stop routing a host. Data-safe by default:
// it deletes the route and reloads the router but leaves the instance running and
// its DB/env in place; --stop also stops+disables an instance's unit.
func runRemove(args []string) {
	fs := flag.NewFlagSet("remove", flag.ExitOnError)
	registryPath := fs.String("registry", envOr("LCHAT_REGISTRY", "/data/registry.db"), "router registry SQLite path")
	unitTmpl := fs.String("unit", envOr("LCHAT_UNIT", "lchat@"), "systemd instance unit template prefix")
	botUnit := fs.String("bot-unit", envOr("LCHAT_BOT_UNIT", "lchat-bot@"), "systemd bot unit template prefix")
	routerUnit := fs.String("router-unit", envOr("LCHAT_ROUTER_UNIT", "lchat-router"), "router systemd unit to reload")
	stop := fs.Bool("stop", false, "for an instance, also stop + disable its systemd unit (DB/env still kept)")
	_ = fs.Parse(reorderFlagsFirst(fs, args))

	host := strings.ToLower(strings.TrimSpace(fs.Arg(0)))
	if !validHost(host) {
		die("remove: invalid host %q", host)
	}
	reg, err := openRegistry(*registryPath)
	if err != nil {
		die("remove: open registry: %v", err)
	}
	rt, err := reg.get(host)
	if err != nil {
		die("remove: %v", err)
	}
	if rt == nil {
		die("remove: unknown host %q", host)
	}
	if err := reg.delete(host); err != nil {
		die("remove: %v", err)
	}
	if rt.Kind == "instance" {
		// An instance's webhook-ingest route (in.<host>, add-hooks) is part of
		// the instance: drop it too so the ingest URL dies with the space.
		if err := reg.delete("in." + host); err != nil {
			die("remove: %v", err)
		}
	}
	if err := systemctl("reload", *routerUnit); err != nil {
		die("remove: reload %s: %v", *routerUnit, err)
	}
	// Tombstone the mesh peers too (#1346) — same reasoning as deleteInstance.
	if rt.Kind == "instance" {
		if hc, hcErr := hibernateConfigFromEnv(); hcErr == nil {
			fanOutMeshRouteDelete(hc, host)
		}
	}
	if *stop && rt.Kind == "instance" {
		_ = systemctl("disable", "--now", *botUnit+host)       // best-effort: a sidecar may not exist
		_ = systemctl("disable", "--now", "lchat-hooks@"+host) // best-effort: same for webhook ingest
		if err := systemctl("disable", "--now", *unitTmpl+host); err != nil {
			fmt.Printf("removed %s (route deleted), but stopping the unit failed: %v\n", host, err)
			return
		}
		fmt.Printf("removed %s (route deleted, instance + sidecar stopped; DB/env kept in place)\n", host)
		return
	}
	fmt.Printf("removed %s (route deleted, router reloaded)\n", host)
	if rt.Kind == "instance" {
		fmt.Printf("  note: instance %s%s is still running and its DB/env remain; pass --stop to stop it\n", *unitTmpl, host)
	}
}

// canReset reports why host may not be reset, or nil if it may. The canary gate
// IS the safety model: reset wipes a live DB, so it refuses anything not
// explicitly flagged throwaway (registry.go: Route.Canary) — a real member
// instance can never be wiped by this command, whatever its hostname.
func canReset(rt *Route) error {
	if rt == nil {
		return fmt.Errorf("unknown host")
	}
	if rt.Kind != "instance" {
		return fmt.Errorf("%q is a %s route, not an instance", rt.Host, rt.Kind)
	}
	if !rt.Canary {
		return fmt.Errorf("%q is not flagged as a canary — refusing to wipe a real instance's data. "+
			"If it is genuinely a throwaway: lchat canary %s --on", rt.Host, rt.Host)
	}
	return nil
}

// archiveInstanceDB moves host's database (and blob dir) into /data/trash,
// keeping its env/vapid so the admin token + config survive — the wipe half of
// `lchat reset`. Recoverable, like remove/reaper (never a destroy).
func archiveInstanceDB(host string) error {
	trash := filepath.Join(instanceDataDir, "trash", fmt.Sprintf("%s-reset-%d", host, time.Now().Unix()))
	if err := os.MkdirAll(trash, 0o700); err != nil {
		return fmt.Errorf("trash dir: %v", err)
	}
	names := []string{host + ".db", host + ".db-wal", host + ".db-shm", host + ".db" + litestream.MetaDirSuffix, host + "-blobs"}
	for _, name := range names {
		src := filepath.Join(instanceDataDir, name)
		if _, err := os.Stat(src); err == nil {
			if err := os.Rename(src, filepath.Join(trash, name)); err != nil {
				return fmt.Errorf("archive %s: %v", name, err)
			}
		}
	}
	return nil
}

// runReset: `lchat reset <host>` — wipe a CANARY's database in place for a fresh
// first-run, the operator-clean answer to "reset this throwaway" (the in-place
// `rm` an operator can't do under the hardening). Stop the unit, archive its DB
// to trash, restart — the instance process (User=lchat) recreates an empty DB
// with correct ownership on boot — then mint the fresh onboarding link.
func runReset(args []string) {
	fs := flag.NewFlagSet("reset", flag.ExitOnError)
	registryPath := fs.String("registry", envOr("LCHAT_REGISTRY", "/data/registry.db"), "router registry SQLite path")
	unitTmpl := fs.String("unit", envOr("LCHAT_UNIT", "lchat@"), "systemd instance unit template prefix")
	yes := fs.Bool("yes", false, "confirm the destructive wipe (required — reset deletes the DB)")
	_ = fs.Parse(reorderFlagsFirst(fs, args))

	host := strings.ToLower(strings.TrimSpace(fs.Arg(0)))
	if !validHost(host) {
		die("reset: invalid host %q", host)
	}
	reg, err := openRegistry(*registryPath)
	if err != nil {
		die("reset: open registry: %v", err)
	}
	rt, err := reg.get(host)
	if err != nil {
		die("reset: %v", err)
	}
	if err := canReset(rt); err != nil {
		die("reset: %v", err)
	}
	if !*yes {
		die("reset: this DELETES %s's database (archived to /data/trash; env/config kept). Re-run with --yes to confirm.", host)
	}

	if err := systemctl("stop", *unitTmpl+host); err != nil {
		die("reset: stop %s: %v", host, err)
	}
	if err := archiveInstanceDB(host); err != nil {
		_ = systemctl("start", *unitTmpl+host) // never leave it stopped after a failed wipe
		die("reset: %v", err)
	}
	if err := systemctl("start", *unitTmpl+host); err != nil {
		die("reset: start %s: %v", host, err)
	}

	// The instance is booting a fresh DB; mint the onboarding link once it answers.
	env, err := readEnvFile(filepath.Join(instanceDataDir, host+".env"))
	if err != nil {
		die("reset: %v (instance restarted fresh; mint later: lchat setup-invite %s)", err, host)
	}
	socket := filepath.Join(instanceSocketDir, host+".sock")
	var link string
	for i := 0; i < 20; i++ {
		if link, err = mintSetupInvite(socketClient(socket), "http://lchat", "https://"+host, env["LCHAT_ADMIN_TOKEN"]); err == nil {
			break
		}
		time.Sleep(300 * time.Millisecond)
	}
	if err != nil {
		fmt.Printf("reset %s — DB wiped (archived to /data/trash), instance restarted fresh.\n"+
			"  (setup link not ready yet: %v — mint it: lchat setup-invite %s)\n", host, err, host)
		return
	}
	fmt.Printf("reset %s — DB wiped (archived to /data/trash), instance restarted fresh.\n"+
		"  onboarding link (one-time, makes you the admin):\n  %s\n", host, link)
}

// runInstances: `lchat instances` — the route/status table.
func runInstances(args []string) {
	fs := flag.NewFlagSet("instances", flag.ExitOnError)
	registryPath := fs.String("registry", envOr("LCHAT_REGISTRY", "/data/registry.db"), "router registry SQLite path")
	_ = fs.Parse(reorderFlagsFirst(fs, args))
	reg, err := openRegistry(*registryPath)
	if err != nil {
		die("instances: %v", err)
	}
	routes, err := reg.list()
	if err != nil {
		die("instances: %v", err)
	}
	if len(routes) == 0 {
		fmt.Println("(no routes)")
		return
	}
	fmt.Printf("%-34s %-9s %-9s %-12s %-9s %-7s %-11s %s\n", "HOST", "KIND", "STATUS", "VERSION", "HIBERNATE", "CANARY", "REPLICATION", "SOCKET")
	for _, r := range routes {
		ver := r.Version
		if ver == "" {
			ver = "-"
		}
		// "-" for the common (systemd-managed) case keeps the table quiet;
		// hibernating hosts stand out at a glance.
		hib := "-"
		if r.Hibernate {
			hib = "yes"
		}
		// Replication class: hibernating hosts show their effective class
		// (unset = stream); a class staged on a systemd-managed host shows too
		// (it's inert but deliberate); "-" = nothing set, nothing replicating.
		repl := r.Replication
		if repl == "" {
			if r.Hibernate {
				repl = replicationStream
			} else {
				repl = "-"
			}
		}
		can := "-"
		if r.Canary {
			can = "canary"
		}
		fmt.Printf("%-34s %-9s %-9s %-12s %-9s %-7s %-11s %s\n", r.Host, r.Kind, r.Status, ver, hib, can, repl, r.Socket)
		if r.LastError != "" {
			fmt.Printf("  last error: %s\n", r.LastError)
		}
	}
}

// runReplication: `lchat replication <host> [class]` — read or set one
// instance's replication class on the activator's S3 replica (the per-plan
// durability ladder: stream / batched / daily; registry.go has the intervals).
// The class is read at wake time, so a set takes effect on the host's next
// wake — an awake instance keeps its current tick until it sleeps. Setting a
// class on a systemd-managed (non-hibernating) host is allowed but inert: it
// pre-stages the class for a later hibernate flip.
func runReplication(args []string) {
	fs := flag.NewFlagSet("replication", flag.ExitOnError)
	registryPath := fs.String("registry", envOr("LCHAT_REGISTRY", "/data/registry.db"), "router registry SQLite path")
	routerUnit := fs.String("router-unit", envOr("LCHAT_ROUTER_UNIT", "lchat-router"), "router systemd unit to reload")
	_ = fs.Parse(reorderFlagsFirst(fs, args))

	host := strings.ToLower(strings.TrimSpace(fs.Arg(0)))
	if !validHost(host) {
		die("replication: invalid host %q (usage: lchat replication <host> [stream|batched|daily])", host)
	}
	reg, err := openRegistry(*registryPath)
	if err != nil {
		die("replication: open registry: %v", err)
	}
	rt, err := reg.get(host)
	if err != nil {
		die("replication: %v", err)
	}
	if rt == nil {
		die("replication: unknown host %q", host)
	}
	if rt.Kind != "instance" {
		die("replication: %q is a %s route, not an instance", host, rt.Kind)
	}

	effective := func(class string) string {
		if class == "" {
			return replicationStream
		}
		return class
	}
	describe := map[string]string{
		replicationStream:  "change-driven S3 sync (~1s) — a hard crash loses seconds",
		replicationBatched: "S3 sync at most every 5m — a hard crash loses minutes",
		replicationDaily:   "S3 sync at wake, then at most every 24h — a hard crash loses up to a day",
	}

	class := strings.ToLower(strings.TrimSpace(fs.Arg(1)))
	if class == "" {
		fmt.Printf("%s: %s (%s)\n", host, effective(rt.Replication), describe[effective(rt.Replication)])
		if !rt.Hibernate {
			fmt.Println("  note: this host is systemd-managed (not hibernating) — the class is inert; the box-wide litestream replicates it")
		}
		return
	}
	if err := reg.setReplication(host, class); err != nil {
		die("replication: %v", err)
	}
	fmt.Printf("%s replication → %s: %s\n", host, class, describe[class])
	fmt.Println("  every graceful sleep/deploy/shutdown still flushes in full — the class only bounds hard-crash loss while awake")
	if !rt.Hibernate {
		fmt.Println("  note: this host is systemd-managed (not hibernating) — the class is stored but inert until a hibernate flip")
		return
	}
	// The router's route map only swaps on reload; without it the new class
	// never reaches a wake. The registry write above is durable either way, so
	// a failed reload is a warning (reload by hand), not a dead flip.
	if err := systemctl("reload", *routerUnit); err != nil {
		fmt.Printf("  WARNING: reload %s failed (%v) — the class is stored but inert until the router reloads\n", *routerUnit, err)
		return
	}
	fmt.Println("  takes effect at the next wake (an awake instance keeps its current tick until it sleeps)")
}

// runHibernate: `lchat hibernate <host> --on|--off` — flip one instance between
// systemd-managed (always-on) and activator-managed (hibernating). Per-host by
// design: a production canary can hibernate while the rest of the fleet stays
// on its units. --on requires the router to be running with
// LCHAT_HIBERNATE_BUCKET, or the host will sit unwakeable once its unit stops.
func runCanary(args []string) {
	fs := flag.NewFlagSet("canary", flag.ExitOnError)
	registryPath := fs.String("registry", envOr("LCHAT_REGISTRY", "/data/registry.db"), "router registry SQLite path")
	on := fs.Bool("on", false, "mark the instance as a throwaway canary")
	off := fs.Bool("off", false, "clear the canary flag (a real, keep-its-data instance)")
	_ = fs.Parse(reorderFlagsFirst(fs, args))

	if *on == *off {
		die("canary: pass exactly one of --on / --off")
	}
	host := strings.ToLower(strings.TrimSpace(fs.Arg(0)))
	if !validHost(host) {
		die("canary: invalid host %q", host)
	}
	reg, err := openRegistry(*registryPath)
	if err != nil {
		die("canary: open registry: %v", err)
	}
	rt, err := reg.get(host)
	if err != nil {
		die("canary: %v", err)
	}
	if rt == nil {
		die("canary: unknown host %q", host)
	}
	if rt.Kind != "instance" {
		die("canary: %q is a %s route, not an instance", host, rt.Kind)
	}
	if err := reg.setCanary(host, *on); err != nil {
		die("canary %s: %v", host, err)
	}
	if *on {
		fmt.Printf("%s is flagged as a canary (throwaway test instance)\n", host)
	} else {
		fmt.Printf("%s is no longer flagged as a canary\n", host)
	}
}

func runHibernate(args []string) {
	fs := flag.NewFlagSet("hibernate", flag.ExitOnError)
	registryPath := fs.String("registry", envOr("LCHAT_REGISTRY", "/data/registry.db"), "router registry SQLite path")
	unitTmpl := fs.String("unit", envOr("LCHAT_UNIT", "lchat@"), "systemd instance unit template prefix")
	botUnit := fs.String("bot-unit", envOr("LCHAT_BOT_UNIT", "lchat-bot@"), "systemd bot unit template prefix")
	routerUnit := fs.String("router-unit", envOr("LCHAT_ROUTER_UNIT", "lchat-router"), "router systemd unit to reload")
	on := fs.Bool("on", false, "hand the instance to the activator: stop+disable its unit; the router wakes it per request")
	off := fs.Bool("off", false, "hand the instance back to systemd: the activator releases it, then its unit is enabled+started")
	_ = fs.Parse(reorderFlagsFirst(fs, args))

	if *on == *off {
		die("hibernate: pass exactly one of --on / --off")
	}
	host := strings.ToLower(strings.TrimSpace(fs.Arg(0)))
	if !validHost(host) {
		die("hibernate: invalid host %q", host)
	}
	reg, err := openRegistry(*registryPath)
	if err != nil {
		die("hibernate: open registry: %v", err)
	}
	rt, err := reg.get(host)
	if err != nil {
		die("hibernate: %v", err)
	}
	if rt == nil {
		die("hibernate: unknown host %q", host)
	}
	if rt.Kind != "instance" {
		die("hibernate: %q is a %s route, not an instance", host, rt.Kind)
	}
	if rt.Status != "ready" {
		die("hibernate: %s is %s, not ready — fix the instance first", host, rt.Status)
	}
	if *on {
		if rt.Hibernate && !unitActive(*unitTmpl+host) {
			fmt.Printf("%s is already hibernating\n", host)
			return
		}
		// Flag set but the unit still runs = a re-run after the litestream
		// guard's two-step (the error message PROMISES this re-run works —
		// hit live on the first bulk flip, where the early-exit above
		// stranded hosts flagged-but-materialized). Fall through and finish
		// the handover; hibernateOn is idempotent over an already-set flag.
		if err := hibernateOn(reg, rt, *unitTmpl, *botUnit, *routerUnit); err != nil {
			die("hibernate %s --on: %v", host, err)
		}
		fmt.Printf("%s is now activator-managed: unit stopped+disabled; the router wakes it per request and sleeps it when idle\n", host)
		if _, err := os.Stat(botEnvPath(host)); err == nil {
			fmt.Printf("  bot sidecar: co-managed by the activator — spawned on each wake, stopped at each sleep (%s%s disabled; --off hands it back to systemd)\n", *botUnit, host)
		}
		return
	}
	if !rt.Hibernate {
		fmt.Printf("%s is not hibernating\n", host)
		return
	}
	if err := hibernateOff(reg, rt, *unitTmpl, *botUnit, *routerUnit); err != nil {
		die("hibernate %s --off: %v", host, err)
	}
	fmt.Printf("%s is back under systemd: unit enabled and healthy; the activator has released it\n", host)
}

// hibernateOn flips a running, systemd-managed instance to activator-managed.
// Ordering — chosen so the host is never left unserveable:
//
//  1. Flag the route. A registry write alone changes nothing live (the
//     router's map only swaps on reload), so a crash right after leaves the
//     unit serving exactly as before.
//  2. Stop + disable the unit — BEFORE the reload, because once the route is
//     activator-managed the first wake's child must be able to bind the
//     socket, and the instance refuses to clobber a live listener (listen()
//     in main.go): a still-running unit would turn every wake into "socket
//     already in use" 503s. This opens the one unavoidable gap — the socket
//     is dead until the wake in step 4 — and requests in it ride the router's
//     13s dial-retry window, the same shape as a deploy restart. Disable (not
//     just stop) so a reboot can't resurrect the unit to fight the activator.
//     The bot sidecar unit (if the host has one staged) goes down here too —
//     the activator co-spawns the sidecar with each wake from now on.
//  3. Reload the router: the route becomes activator-managed.
//  4. A warm request through the public path — best-effort, but it both
//     closes the gap immediately (the wake binds the socket, so any retrying
//     dials from step 2 connect) and proves the wake path works while the
//     operator is still watching.
//
// Nothing is checkpointed here and no S3 is touched: the DB is already local,
// so the first wake's restore sees it as the warm cache and skips; replication
// under the fresh lease is what backfills S3.
// unitActive reports whether the systemd unit is running — the discriminator
// between "already fully hibernating" and "flag set, handover unfinished"
// (the litestream guard's two-step leaves exactly that state behind).
func unitActive(unit string) bool {
	return systemctlQuery("is-active", "--quiet", unit) == nil
}

func hibernateOn(reg *Registry, rt *Route, unitTmpl, botUnit, routerUnit string) error {
	// Existing instances' env files were written for the systemd path (root
	// reads them); the router's activator reads them as the service user, so
	// hand the file over first — a flip that can't wake is worse than no flip.
	if err := matchOwner(filepath.Join(instanceDataDir, rt.Host+".env"), instanceDataDir); err != nil {
		return fmt.Errorf("env file ownership: %v", err)
	}
	if err := reg.setHibernate(rt.Host, true); err != nil {
		return fmt.Errorf("flag: %v", err)
	}
	// Two litestream processes on one DB share the same derived meta dir and
	// corrupt each other's LTX state (hit live on the first real flip: the
	// box-wide backup replicator still tracked the host when the activator's
	// embedded one started, and a config regen yanked files out from under
	// it — a stuck error loop and failed checkpoints). The flag is set above
	// ON PURPOSE before this guard: the operator's fix — re-running the backup
	// script, which excludes hibernate=1 hosts — only works because the flag
	// already reads true, and the flag is inert until the router reload that
	// happens only after this guard passes.
	if litestreamConfigTracks(rt.Host) {
		return fmt.Errorf("%s is still replicated by the box-wide litestream (%s): re-run deploy/fleet-backup.sh — it now excludes this host, the flag is already set — then run this flip again", rt.Host, litestreamConfigPath())
	}
	if err := systemctl("disable", "--now", unitTmpl+rt.Host); err != nil {
		return fmt.Errorf("stop unit: %v (flag is set but the unit still runs — the host serves as before; re-run, or undo with `lchat hibernate %s --off`)", err, rt.Host)
	}
	if _, err := os.Stat(botEnvPath(rt.Host)); err == nil {
		// The bot sidecar hands over too: from here the activator co-spawns it
		// with each wake and stops it at each sleep, so the always-on unit
		// must go — two sidecars would double every bot reply. Before the
		// reload, like the instance unit, so a systemd sidecar and a
		// co-spawned one never overlap. Best-effort: a sidecar that won't
		// stop cleanly must not strand the flip (members > bots).
		_ = systemctl("disable", "--now", botUnit+rt.Host)
		// Same ownership handover as the instance env above, for the pieces
		// the co-spawned sidecar (a router child, running as the service
		// user) reads and writes. Non-recursive on purpose: the session files
		// inside were already written by the unit's service user, and add-bot
		// chowns fresh ones at creation.
		_ = matchOwner(botEnvPath(rt.Host), instanceDataDir)
		_ = matchOwner(botSessionDir(rt.Host), instanceDataDir)
	}
	if err := systemctl("reload", routerUnit); err != nil {
		return fmt.Errorf("reload %s: %v (unit is stopped — reload the router by hand to bring the host back)", routerUnit, err)
	}
	confirmPublicReady(rt.Host, routerHTTPSAddr)
	return nil
}

// hibernateOff flips an activator-managed instance back under systemd. The
// mirror of hibernateOn, with one extra wait:
//
//  1. Clear the flag (inert until reload).
//  2. Reload the router: the map swap stops routing requests through the
//     activator, and the reload-time reconcile (retireExcept, activator.go)
//     makes the activator release the host — stop the child if it's awake,
//     take the final checkpoint, give the S3 lease back.
//  3. WAIT for the child to actually let go of the socket before starting the
//     unit. The release is asynchronous inside the router process and the
//     instance refuses to start over a live listener, so enabling the unit too
//     early would just crash-loop it against the child. Dial-probing the
//     socket is the narrowest thing observable from outside the router: quiet
//     means the child's listener is gone (an already-asleep host has none, so
//     this returns on the first probe). The final S3 checkpoint may still be
//     finishing when the unit starts — that's fine: the replica goes stale by
//     design once the flag is off, and a later flip back on wakes from the
//     local DB (the warm cache, which is the newer truth).
//  4. Enable + start the unit and health-check it, exactly like add-instance.
//     A staged bot sidecar then goes back on its always-on unit (instance
//     first, then sidecar — the same bootstrap order add-bot documents).
//
// Requests between the child's stop and the unit binding ride the router's 13s
// dial-retry window, same as a deploy restart.
func hibernateOff(reg *Registry, rt *Route, unitTmpl, botUnit, routerUnit string) error {
	if err := reg.setHibernate(rt.Host, false); err != nil {
		return fmt.Errorf("flag: %v", err)
	}
	if err := systemctl("reload", routerUnit); err != nil {
		return fmt.Errorf("reload %s: %v (flag is cleared; reload by hand, then re-run)", routerUnit, err)
	}
	if err := waitSocketQuiet(rt.Socket, hibernateReleaseTimeout); err != nil {
		return fmt.Errorf("%v — the activator hasn't released %s yet (a long final checkpoint?); re-run once it has", err, rt.Host)
	}
	unit := unitTmpl + rt.Host
	if err := systemctl("enable", "--now", unit); err != nil {
		return fmt.Errorf("start %s: %v", unit, err)
	}
	if err := waitHealthy(rt.Socket, 20*time.Second); err != nil {
		return fmt.Errorf("%v (unit started but unhealthy — check journalctl -u %s)", err, unit)
	}
	// Hand the sidecar back too: the co-spawned one died with the activator's
	// child (the retire's stop takes the sidecar down first), so a host with
	// one staged returns to its always-on unit — after the instance is
	// healthy, matching add-bot's "instance first" bootstrap order. A failure
	// here doesn't fail the flip (the instance is fine); tell the operator.
	if _, err := os.Stat(botEnvPath(rt.Host)); err == nil {
		if err := systemctl("enable", "--now", botUnit+rt.Host); err != nil {
			fmt.Printf("  warning: sidecar unit %s%s failed to start: %v — start it by hand\n", botUnit, rt.Host, err)
		}
	}
	return nil
}

// hibernateReleaseTimeout bounds how long a flip-off waits for the activator to
// release the child: the stop path's own budgets (next-due probe 5s + SIGTERM
// drain 20s + final checkpoint 30s) total under a minute; leave headroom. A var
// so tests can shrink the failure path.
var hibernateReleaseTimeout = 90 * time.Second

// waitSocketQuiet blocks until nothing accepts on the socket (or the timeout
// elapses) — how the flip-off observes, from outside the router process, that
// the activator's child has released the socket. A dial failure is the "quiet"
// signal whether the socket file lingers (ECONNREFUSED) or not (ENOENT).
func waitSocketQuiet(socket string, timeout time.Duration) error {
	deadline := time.Now().Add(timeout)
	for {
		c, err := net.DialTimeout("unix", socket, 500*time.Millisecond)
		if err != nil {
			return nil
		}
		c.Close()
		if time.Now().After(deadline) {
			return fmt.Errorf("socket %s still has a listener after %s", socket, timeout)
		}
		time.Sleep(250 * time.Millisecond)
	}
}

// runAdminLink: `lchat admin-link <host>` — recover the admin link from the
// instance's EnvironmentFile (the DB holds only the token's hash).
func runAdminLink(args []string) {
	fs := flag.NewFlagSet("admin-link", flag.ExitOnError)
	_ = fs.Parse(reorderFlagsFirst(fs, args))
	host := strings.ToLower(strings.TrimSpace(fs.Arg(0)))
	if !validHost(host) {
		die("admin-link: invalid host %q", host)
	}
	envPath := filepath.Join(instanceDataDir, host+".env")
	env, err := readEnvFile(envPath)
	if err != nil {
		die("admin-link: %v", err)
	}
	tok := env["LCHAT_ADMIN_TOKEN"]
	if tok == "" {
		die("admin-link: no LCHAT_ADMIN_TOKEN in %s", envPath)
	}
	fmt.Printf("https://%s/admin#token=%s\n", host, tok)
}

// runDeploy: `lchat deploy <host>` (or --all) — restart the instance(s) so they
// pick up a new binary. SIGTERM drains gracefully and the router retries dials
// across the brief gap, so the swap drops no requests.
//
// With --version <ver> it first repoints the instance's /opt/lchat/live/<host>
// symlink at that staged version (see `lchat stage`), then health-checks that the
// instance actually reports that build — auto-rolling-back to the prior version if
// it doesn't. That's the side-by-side path: `deploy test --version <ver>` moves one
// instance while the rest stay put; `deploy --all --version <ver>` promotes.
//
// Without --version it just restarts on the instance's current version — the
// classic "I've already swapped the binary" path. See docs/instance-router.md.
func runDeploy(args []string) {
	fs := flag.NewFlagSet("deploy", flag.ExitOnError)
	registryPath := fs.String("registry", envOr("LCHAT_REGISTRY", "/data/registry.db"), "router registry SQLite path")
	unitTmpl := fs.String("unit", envOr("LCHAT_UNIT", "lchat@"), "systemd instance unit template prefix")
	all := fs.Bool("all", false, "deploy every instance, one at a time (skips pinned canaries — see --include-pinned)")
	verFlag := fs.String("version", "", "point the instance(s) at this staged version before restarting (see `lchat stage`)")
	pinFlag := fs.Bool("pin", false, "also pin the instance(s) to --version, so the auto-updater leaves them alone (the canary flow)")
	includePinned := fs.Bool("include-pinned", false, "let --all move pinned instances too (a pinned host is someone's live canary — override deliberately)")
	_ = fs.Parse(reorderFlagsFirst(fs, args))

	ver := strings.TrimSpace(*verFlag)
	if ver != "" {
		if !validVersion(ver) {
			die("deploy: invalid version %q", ver)
		}
		if _, err := os.Stat(versionBinPath(ver)); err != nil {
			die("deploy: version %q is not staged — run `lchat stage --file <binary>` first", ver)
		}
	}
	if *pinFlag && ver == "" {
		die("deploy: --pin requires --version (a pin names one exact build)")
	}
	if *pinFlag && *all {
		die("deploy: --pin with --all would pin the whole fleet — pin one canary at a time")
	}

	unlock, err := acquireDeployLock()
	if err != nil {
		die("deploy: %v", err)
	}
	defer unlock()

	reg, err := openRegistry(*registryPath)
	if err != nil {
		die("deploy: open registry: %v", err)
	}
	hosts, err := deployTargets(reg, *all, fs.Arg(0), "deploy")
	if err != nil {
		die("%v", err)
	}

	for _, host := range hosts {
		rt, err := reg.get(host)
		if err != nil {
			die("deploy %s: %v", host, err)
		}
		if rt == nil {
			die("deploy %s: unknown host (run add-instance first)", host)
		}
		if rt.Kind != "instance" {
			die("deploy %s: not an instance (kind %q) — only messenger instances are deployed", host, rt.Kind)
		}
		// A fleet sweep leaves pinned instances alone: a pin is someone's live
		// canary (CLAUDE.md § per-session canaries), and until now only the
		// AUTO-updater honoured it — `deploy --all` was the loophole that
		// stomped a pinned canary onto the channel build while its pin sat
		// intact. Naming a host explicitly still deploys it (that's intent);
		// --include-pinned overrides the sweep on purpose.
		if *all && ver != "" && !*includePinned {
			if skip, why := sweepSkipsPinned(rt, ver); skip {
				fmt.Printf("skipped %s (%s — move it with `lchat deploy %s --version %s --pin`, or rerun with --include-pinned)\n", host, why, host, ver)
				continue
			} else if why != "" {
				fmt.Printf("note: %s: %s\n", host, why)
			}
		}
		if rt.Hibernate {
			// No unit to restart — and starting one would fight the activator's
			// child for the socket. A --version deploy is still meaningful as a
			// pure repoint (the next wake execs it — same dance as the
			// auto-updater's hibernating phase, and the rescue path for a bad
			// repointed build). A plain restart-deploy has nothing to restart.
			if ver == "" {
				if *all {
					fmt.Printf("skipped %s (hibernating — nothing to restart; use --version to repoint)\n", host)
					continue
				}
				die("deploy %s: instance is hibernating (no unit to restart) — use --version to repoint it for its next wake", host)
			}
			cur, _ := liveVersion(host)
			if cur == ver {
				fmt.Printf("deployed %s (already on %s)\n", host, ver)
				continue
			}
			if err := pointLive(host, ver); err != nil {
				die("deploy %s: %v", host, err)
			}
			if err := reg.setVersions(host, ver, cur); err != nil {
				die("deploy %s: repointed but recording the version failed: %v", host, err)
			}
			fmt.Printf("deployed %s @ %s (hibernating — no health check; runs it on next wake)\n", host, ver)
			if *pinFlag {
				// The pin lives in the instance's DB, written over its socket —
				// which wakes it, onto the build just repointed. Deliberate: a
				// pinned deploy is a canary, and its operator is about to poke
				// it anyway.
				if err := pinHost(rt, ver); err != nil {
					die("deploy %s: deployed @ %s but PINNING FAILED (%v) — the next update pass may move it; retry with `lchat update pin %s %s`", host, ver, err, host, ver)
				}
				fmt.Printf("pinned %s to %s (auto-updates paused; the pin write woke it)\n", host, ver)
			}
			continue
		}
		unit := *unitTmpl + host

		if ver == "" {
			// Restart on the current version (binary already in place).
			if err := systemctl("restart", unit); err != nil {
				die("deploy %s: restart: %v", host, err)
			}
			if err := waitHealthy(rt.Socket, 20*time.Second); err != nil {
				die("deploy %s: %v", host, err)
			}
			fmt.Printf("deployed %s\n", host)
			continue
		}

		// --version: repoint, restart, verify the build took, roll back if not.
		changed, err := deployHostVersion(reg, rt, unit, ver)
		if err != nil {
			die("deploy %s: %v", host, err)
		}
		if changed {
			fmt.Printf("deployed %s @ %s\n", host, ver)
		} else {
			fmt.Printf("deployed %s (already on %s)\n", host, ver)
		}
		if *pinFlag {
			// The deploy stands even if the pin write fails — say so precisely.
			if err := pinHost(rt, ver); err != nil {
				die("deploy %s: deployed @ %s but PINNING FAILED (%v) — the next update pass may move it; retry with `lchat update pin %s %s`", host, ver, err, host, ver)
			}
			fmt.Printf("pinned %s to %s (auto-updates paused)\n", host, ver)
		} else if prefs, err := fetchUpdatePrefs(rt.Socket); err == nil && prefs.Pin != "" && prefs.Pin != ver {
			// A stale pin silently freezes the instance on what was just
			// deployed — surface it so the operator decides.
			fmt.Printf("note: %s is still pinned to %s — auto-updates stay paused; `lchat update pin %s %s` to repin here, or `lchat update unpin %s` to resume its channel\n",
				host, prefs.Pin, host, ver, host)
		}
	}
}

// sweepSkipsPinned decides whether a fleet sweep (`deploy --all --version`)
// leaves this host alone, returning the reason to print either way. Split
// failure policies, both deliberate:
//   - a RUNNING host whose prefs can't be fetched is probably crashed — the
//     sweep is how it gets rescued, so deploy anyway (with a note);
//   - a HIBERNATING host whose parked DB can't be read fails CLOSED (skip),
//     matching the auto-updater: its pin may live only in the unreadable
//     copy, and "the one host that must not move, moves" is the failure
//     that matters. It converges once a wake leaves a warm local DB.
func sweepSkipsPinned(rt *Route, ver string) (skip bool, why string) {
	var prefs updatePrefs
	var err error
	if rt.Hibernate {
		if prefs, err = hibernatingPrefs(rt.Host); err != nil {
			return true, fmt.Sprintf("hibernating and its parked prefs are unreadable (%v) — pin unknown, left alone", err)
		}
	} else if prefs, err = fetchUpdatePrefs(rt.Socket); err != nil {
		return false, fmt.Sprintf("couldn't read update prefs (%v) — deploying anyway", err)
	}
	if prefs.Pin != "" && prefs.Pin != ver {
		return true, "pinned to " + prefs.Pin + " — a canary"
	}
	return false, ""
}

// deployHostVersion is the one per-host apply dance, shared by `deploy
// --version` and the auto-updater (updater.go): repoint the live symlink at a
// staged version, restart, verify the instance actually reports that build,
// roll back on failure, and record current+previous in the registry. Returns
// changed=false when the host was already on ver.
//
// deployHealthTimeout is a var so tests can shrink the failure path's wait.
var deployHealthTimeout = 20 * time.Second

func deployHostVersion(reg *Registry, rt *Route, unit, ver string) (changed bool, err error) {
	host := rt.Host
	prev, _ := liveVersion(host) // "" if this instance isn't versioned yet
	if prev == ver {
		return false, nil
	}
	if err := pointLive(host, ver); err != nil {
		return false, err
	}
	if err := systemctl("restart", unit); err != nil {
		rollbackLive(host, prev, unit, rt.Socket)
		return false, fmt.Errorf("restart: %v (rolled back to %q)", err, prev)
	}
	if err := waitHealthyVersion(rt.Socket, ver, deployHealthTimeout); err != nil {
		rollbackLive(host, prev, unit, rt.Socket)
		return false, fmt.Errorf("failed health check (%v), rolled back to %q", err, prev)
	}
	rt.PrevVersion, rt.Version = prev, ver
	// Narrow UPDATE, not a full upsert: rt was read before a possibly-long
	// download, and writing every column back would clobber whatever the
	// activator or an operator changed meanwhile (next_due, hibernate).
	if err := reg.setVersions(host, ver, prev); err != nil {
		return true, fmt.Errorf("record version: %v", err)
	}
	restartBotSidecar(host)
	restartHooksSidecar(host)
	return true, nil
}

// restartBotSidecar best-effort re-execs a host's bot sidecar so it picks up the
// same versioned binary the instance now runs — the bot execs /opt/lchat/live/<host>
// too (deploy/systemd/lchat-bot@.service), so restarting it after the live symlink
// moves keeps the bot's code in lock-step with the app. `try-restart` is a no-op when
// no sidecar is active, so instances without a bot are untouched; a bot hiccup only
// logs and never fails an otherwise-healthy instance deploy.
func restartBotSidecar(host string) {
	if err := systemctl("try-restart", "lchat-bot@"+host); err != nil {
		log.Printf("deploy: bot sidecar restart for %s failed (instance is healthy on the new version): %v", host, err)
	}
}

// restartHooksSidecar: same lock-step contract for the webhook-ingest sidecar
// (deploy/systemd/lchat-hooks@.service execs the live symlink too).
func restartHooksSidecar(host string) {
	if err := systemctl("try-restart", "lchat-hooks@"+host); err != nil {
		log.Printf("deploy: hooks sidecar restart for %s failed (instance is healthy on the new version): %v", host, err)
	}
}

// acquireDeployLock serialises everything that runs the repoint/restart/
// health-check dance — deploy, rollback, and the timer-fired `update run` —
// across processes, so an auto-update can never interleave with an operator's
// deploy mid-swap. Non-blocking: the second caller gets a clear error rather
// than silently queueing behind an unknown amount of work.
func acquireDeployLock() (func(), error) {
	path := filepath.Join(optDir, ".deploy.lock")
	f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0o644)
	if err != nil {
		return nil, err
	}
	if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB); err != nil {
		f.Close()
		return nil, fmt.Errorf("another deploy/rollback/update is running (%s is held)", path)
	}
	return func() {
		_ = syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
		f.Close()
	}, nil
}

// rollbackLive best-effort restores an instance to prev after a failed
// --version deploy: repoint the symlink and restart. If there is no prev (the
// instance had no version yet) it leaves the failed link in place — the operator
// must intervene either way, and the die() that follows says so.
func rollbackLive(host, prev, unit, socket string) {
	if prev == "" {
		return
	}
	if err := pointLive(host, prev); err != nil {
		return
	}
	_ = systemctl("restart", unit)
	_ = waitHealthy(socket, 20*time.Second)
}

// confirmPublicReady blocks until a freshly-created host answers an HTTPS request
// through the local router (dialed at httpsAddr with host as the SNI, so the real
// router route + cert are exercised), or a short deadline passes. It guarantees
// the setup link works on first click — the visitor reaches a ready admin sign-on
// rather than a mid-provision error — and warms the per-host TLS cert as a side
// effect (the handshake triggers autocert issuance). Best-effort: it returns
// quietly on timeout (the instance already passed its own socket health check, so
// the public path is a beat behind at most). A var so tests can stub it. See
// docs/cloud-provisioner.md.
var confirmPublicReady = func(host, httpsAddr string) {
	client := &http.Client{
		Timeout: 15 * time.Second,
		Transport: &http.Transport{
			// Always dial the local router; the SNI/Host is the real host, so the
			// router serves that host's cert and routes to its instance.
			DialTLSContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
				return (&tls.Dialer{Config: &tls.Config{ServerName: host}}).DialContext(ctx, "tcp", httpsAddr)
			},
		},
	}
	deadline := time.Now().Add(25 * time.Second)
	for time.Now().Before(deadline) {
		resp, err := client.Get("https://" + host + "/")
		if err == nil {
			resp.Body.Close()
			if publicReadyStatus(resp.StatusCode) {
				return
			}
		}
		time.Sleep(500 * time.Millisecond)
	}
}

// publicReadyStatus classifies one probe response: anything the instance
// itself could have answered counts as ready, but 404 is the ROUTER's
// "unknown host" (an instance's "/" always serves a page) — the route hasn't
// landed on whichever box owns this host yet (mesh replication in flight).
// Treating 404 as ready is exactly how a create once handed out a dead space,
// so it waits like any 5xx.
func publicReadyStatus(code int) bool {
	return code < 500 && code != http.StatusNotFound
}

// socketClient returns an HTTP client that dials an instance's unix socket
// (request URLs use the placeholder host http://lchat).
func socketClient(socket string) *http.Client {
	return &http.Client{
		Timeout: 3 * time.Second,
		Transport: &http.Transport{
			DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
				return (&net.Dialer{}).DialContext(ctx, "unix", socket)
			},
		},
	}
}

// waitHealthy blocks until the instance answers an HTTP request on its socket, or
// the timeout elapses. It retries, so it's robust to the restart window (socket
// briefly absent, or a stale socket left by an abruptly-killed old process) — and
// a broken new binary that never becomes healthy fails the deploy before `--all`
// rolls it to the rest of the fleet.
func waitHealthy(socket string, timeout time.Duration) error {
	deadline := time.Now().Add(timeout)
	client := socketClient(socket)
	var last error
	for time.Now().Before(deadline) {
		resp, err := client.Get("http://lchat/")
		if err == nil {
			resp.Body.Close()
			if resp.StatusCode < 500 {
				return nil
			}
			last = fmt.Errorf("unhealthy: HTTP %d", resp.StatusCode)
		} else {
			last = err
		}
		time.Sleep(150 * time.Millisecond)
	}
	return fmt.Errorf("instance not healthy within %s: %v", timeout, last)
}

// waitReachable blocks until the backend accepts a connection and returns any HTTP
// response on its socket, or the timeout elapses. Unlike waitHealthy it accepts any
// status and does not follow redirects — a sibling service's "/" may 3xx/4xx/5xx yet
// still be up; only a failure to connect means "not up".
func waitReachable(socket string, timeout time.Duration) error {
	deadline := time.Now().Add(timeout)
	client := &http.Client{
		Timeout:       3 * time.Second,
		CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
		Transport: &http.Transport{
			DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
				return (&net.Dialer{}).DialContext(ctx, "unix", socket)
			},
		},
	}
	var last error
	for time.Now().Before(deadline) {
		resp, err := client.Get("http://svc/")
		if err == nil {
			resp.Body.Close()
			return nil // any HTTP response means the backend is listening
		}
		last = err
		time.Sleep(150 * time.Millisecond)
	}
	return fmt.Errorf("backend not reachable within %s: %v", timeout, last)
}

// --- helpers ---------------------------------------------------------------

// systemctl is a var so tests can stand in for systemd (e.g. bind the instance
// socket themselves when they see "enable --now"); everything else in the
// creation path — env files, registry, symlinks, health checks — runs for real.
// systemctlQuery is the read-only twin of systemctl (is-active etc.) — its own
// seam so tests asserting exact mutating-call sequences aren't polluted by
// state queries.
var systemctlQuery = func(args ...string) error {
	return exec.Command("systemctl", args...).Run()
}

var systemctl = func(args ...string) error {
	out, err := exec.Command("systemctl", args...).CombinedOutput()
	if err != nil {
		return fmt.Errorf("systemctl %s: %v: %s", strings.Join(args, " "), err, strings.TrimSpace(string(out)))
	}
	return nil
}

// matchOwner chowns path to whatever owns dir — the service user owns /data
// (the box hardening), so this is "give the file to whoever runs the router"
// without parsing systemd units for a user name. A no-op when both are
// already the same (the single-user dev case).
// litestreamConfigPath is where the box-wide backup replicator's config lives
// (deploy/fleet-backup.sh writes it); overridable for tests and unusual boxes.
func litestreamConfigPath() string {
	if p := os.Getenv("LCHAT_LITESTREAM_CONFIG"); p != "" {
		return p
	}
	return "/etc/litestream.yml"
}

// litestreamConfigTracks reports whether the box-wide litestream config still
// lists the host's DB. A missing config means no box-wide replicator (dev
// machines, self-hosters) — not tracked. The check is a plain line match
// against the exact "path: /data/<host>.db" the generator emits; parsing YAML
// for one substring would be ceremony.
func litestreamConfigTracks(host string) bool {
	b, err := os.ReadFile(litestreamConfigPath())
	if err != nil {
		return false
	}
	return strings.Contains(string(b), "path: "+filepath.Join(instanceDataDir, host+".db")+"\n")
}

func matchOwner(path, dir string) error {
	st, err := os.Stat(dir)
	if err != nil {
		return err
	}
	sys, ok := st.Sys().(*syscall.Stat_t)
	if !ok {
		return nil // non-unix stat: nothing to match, nothing to fix
	}
	return os.Chown(path, int(sys.Uid), int(sys.Gid))
}

// writeEnvFile writes KEY=value lines (sorted for a stable file) at 0600 — it
// holds the admin token, so it's operator-secret, like the platform env it
// replaces.
// instanceEnvMap builds a per-instance EnvironmentFile's contents — the ONE
// definition, shared by materializeInstance and the mesh route receiver
// (meshreplicate.go), so a replicated instance wakes with exactly the env its
// creator wrote. Empty values are omitted, like the unit's "-" prefix.
func instanceEnvMap(adminToken, appStoreURL, homeOrigin, pushRelayURL, pushRelayToken, entitlement, groupName string) map[string]string {
	env := map[string]string{"LCHAT_ADMIN_TOKEN": adminToken}
	for k, v := range map[string]string{
		"LCHAT_APP_STORE_URL":    appStoreURL,
		"LCHAT_HOME_ORIGIN":      homeOrigin,
		"LCHAT_PUSH_RELAY_URL":   pushRelayURL,
		"LCHAT_PUSH_RELAY_TOKEN": pushRelayToken,
		"LCHAT_ENTITLEMENT":      entitlement,
		"LCHAT_GROUP_NAME":       groupName,
	} {
		if v != "" {
			env[k] = v
		}
	}
	return env
}

func writeEnvFile(path string, kv map[string]string) error {
	keys := make([]string, 0, len(kv))
	for k := range kv {
		keys = append(keys, k)
	}
	sort.Strings(keys)
	var b strings.Builder
	for _, k := range keys {
		fmt.Fprintf(&b, "%s=%s\n", k, kv[k])
	}
	return os.WriteFile(path, []byte(b.String()), 0o600)
}

// readEnvFile parses a KEY=value EnvironmentFile (blank lines and #comments
// ignored).
func readEnvFile(path string) (map[string]string, error) {
	f, err := os.Open(path)
	if err != nil {
		return nil, err
	}
	defer f.Close()
	m := map[string]string{}
	sc := bufio.NewScanner(f)
	for sc.Scan() {
		line := strings.TrimSpace(sc.Text())
		if line == "" || strings.HasPrefix(line, "#") {
			continue
		}
		if k, v, ok := strings.Cut(line, "="); ok {
			m[strings.TrimSpace(k)] = strings.TrimSpace(v)
		}
	}
	return m, sc.Err()
}

// markInstanceFailed handles a partial add-instance: stop + disable the unit (so it
// can't crash-loop) and record status=failed + last_error for `lchat instances`,
// all best-effort. The env file and DB are KEPT — the env file is the only copy of
// the admin token (the DB stores just its hash), so removing it could strand a
// still-running instance with an unrecoverable token. add-instance overwrites a
// non-ready route on retry, so the failed row doesn't block a re-run.
func markInstanceFailed(reg *Registry, host, unit, reason string) {
	_ = systemctl("disable", "--now", unit)
	if r, err := reg.get(host); err == nil && r != nil {
		r.Status = "failed"
		r.LastError = reason
		_ = reg.upsert(*r)
	}
}