#!/bin/sh
#
#   ------------------------------------------------------------------
#   IF YOU ARE READING THIS IN YOUR TERMINAL, KOSMOS DID NOT INSTALL.
#
#   Nothing went wrong and nothing was broken. This is the installer's
#   own text, printed to your screen instead of being run.
#
#   You need the whole line, including the part at the end:
#
#       curl -fsSL https://installkosmos.com/setup | sh
#
#   Copy that, paste it into Terminal, and press Return.
#   ------------------------------------------------------------------
#
# ⚠️ THE FIRST TWELVE LINES OF THIS FILE ARE WRITTEN FOR SOMEBODY WHO IS NOT
# US, AND THEY EARNED THEIR PLACE. On 2026-08-22 the first person outside this
# team to try Kosmos ran `curl -fsSL .../setup` with no `| sh`. curl did as it
# was asked, printed 2,169 lines of this file to her screen, and exited 0. She
# reported to Josh that the product was broken, and she was being reasonable:
# the failure is silent, succeeds, and looks catastrophic.
#
# Everything below this banner is written for whoever maintains the installer.
# The top of the screen is the one moment we are guaranteed the attention of
# somebody who has just watched two thousand lines scroll past, and it used to
# be spent on /Applications icon staging -- true, careful, and useless to her.
# (Splinter's catch. The page it came from was fixed the same night so the
# command can no longer be half-selected; this is the belt for every other way
# a person can arrive holding half of it.)
#
# Kosmos installer. One line, no sudo, no password. Everything lives in your
# home folder except: the app icon, which goes to /Applications when this
# user can write there without a password (macOS admin accounts can), and
# into the Applications folder inside your home folder otherwise; the
# icon's one-line registration with macOS (so Spotlight knows it exists);
# and, on --uninstall, the launchd bookkeeping that removes agents'
# background jobs. In
# /Applications it only ever replaces a Kosmos icon it can prove it created
# itself (by the icon's own contents); its write check creates and removes
# one empty hidden folder there; and the icon is assembled in a hidden
# .Kosmos.app.stage.<pid> folder beside its spot and renamed into place,
# with the replaced icon renamed aside as .Kosmos.app.old.<pid> until the
# swap completes (an interrupted run can leave either hidden folder
# behind; --uninstall sweeps both when it can prove they are this
# install's own, and names anything it leaves). macOS may show its own one-time
# "Terminal wants to manage apps" dialog for the icon step. It never
# touches any other app. A fresh
# install that confirms its own board is running finishes by launching the
# Kosmos app (#2073: app-only, no browser); updates never do, and
# KOSMOS_NO_OPEN=1 turns it off.
#
# ⚠️ THE SHEBANG SAYS sh BECAUSE THE PAGE SAYS sh. This file's contract is
# the interpreter the marketing line actually invokes: macOS /bin/sh, which
# is bash 3.2 in POSIX mode (the Darwin gate below runs before anything
# non-POSIX, so a Linux dash never gets past the first sentence). `local`
# and `set -o pipefail` are safe under macOS sh specifically, and that is
# the only sh this file supports.
#
#   curl -fsSL https://installkosmos.com/setup | sh
#
# ⚠️ WHO THIS IS FOR, because it governs every decision below. The person running
# this has been handed a line to paste by someone they trust, in a room, and has
# possibly never opened Terminal before. They are not debugging. If something
# goes wrong they will not read a stack trace, they will conclude the product is
# broken and stop. So:
#
#   - EVERY step prints what it is doing BEFORE it does it. A silent install is
#     the documented disqualifying failure (launch decision, 2026-08-11: a
#     silent install disqualifies the product): a blank terminal
#     for several minutes reads as broken, and the person quits before it
#     finishes. Measured on a competitor the same week this was written: ten
#     minutes of no output at all while it downloaded a database.
#   - Every failure prints what to do next, in a sentence, not an error code.
#   - Nothing needs sudo. Nothing is written outside $HOME except: the app
#     icon (and the write probe that decides where it can go), which uses
#     /Applications only when this user can already write there without a
#     password; the icon's one-line registration with macOS
#     (LaunchServices, so Spotlight knows it exists); and, on --uninstall,
#     the launchd enable/bootout that removes agents' background jobs. The
#     header sentence above lists the same three exceptions; when one
#     list changes the other must, because this file is served verbatim at
#     https://installkosmos.com/setup and these sentences are what a cautious
#     person reads before piping it into sh.
#   - Running it twice is safe and says so.
#
# ⚠️ AND IT MUST BE REVERSIBLE. `--uninstall` genuinely returns the machine to
# before. That is not politeness: the first run on a never-touched Mac is the
# most valuable test this project will ever get, and it is worth exactly once
# unless we can put the machine back. One stated bound: anything the
# uninstall cannot PROVE this installer created is left alone and named,
# never deleted; on the rare machine where that leaves something behind,
# the sentence says what it is.

# ⚠️ THE macOS CHECK RUNS BEFORE ANY set OPTION. `set -o pipefail` is not
# POSIX; on a Linux dash the old order died with a raw shell error before
# reaching the friendly "Kosmos runs on macOS" sentence below.
case "$(uname -s)" in
  Darwin) ;;
  *) printf '\n  Kosmos runs on macOS. This looks like %s.\n\n' "$(uname -s)" >&2; exit 1 ;;
esac

set -euo pipefail

KOSMOS_HOME="${KOSMOS_HOME:-$HOME/.local/share/kosmos}"
# Slash-normalized, because install/kosmos self-derives ITS home from its
# own location and the two strings must compare equal: a trailing slash
# on $HOME (measured) made every ownership and board proof in this file
# use //-flavored paths the launcher never bakes.
KOSMOS_HOME="$(printf '%s' "$KOSMOS_HOME" | /usr/bin/tr -s '/')"
KOSMOS_HOME="${KOSMOS_HOME%/}"
# ⚠️ SHELL-SIGNIFICANT CHARACTERS IN KOSMOS_HOME ARE REFUSED OUTRIGHT.
# Two separate mechanisms make them catastrophic rather than awkward. A
# NEWLINE: the ownership checks below prove a bundle is ours with
# `grep -F` on a token built from this value, and grep -F treats a
# newline in the pattern as a pattern SEPARATOR -- the token degrades
# into two alternatives, one of which (`}"`) matches every launcher ever
# written, silently turning every ownership gate on every rm -rf
# fail-OPEN. A QUOTE, DOLLAR, BACKTICK or BACKSLASH: the value is baked
# into the generated .app launcher through an unquoted heredoc, so those
# write a launcher that is syntactically broken or that runs command
# substitution at CLICK time. Same posture as the KOSMOS_HOME=$HOME
# guard on the uninstall path: the catastrophic misuses of an override
# are refused in a sentence, not survived.
# The closing brace is refused for a THIRD mechanism: the launcher bakes
# the value inside ${KOSMOS_HOME:-<value>}, so a } in the value closes the
# expansion early and the launcher runs fine while resolving the WRONG
# home -- an icon that alerts "could not start" forever, reproduced in
# review with /tmp/ku}rt resolving to /tmp/kurt}.
# (--uninstall is refused too, deliberately: its own deletion gates
# depend on this same value, and running them against a poisoned one is
# worse than asking the user to fix it first.)
case "$KOSMOS_HOME" in
  /*) ;;
  *)
    printf '\n  KOSMOS_HOME must be an absolute path (a relative one would resolve against whatever folder the icon is opened from). Unset it and run again.\n\n' >&2
    exit 2
    ;;
esac
# Dot components are refused too: the ownership and board proofs compare
# this string EXACTLY against paths the launcher and the ps table carry,
# and /tmp/./k versus /tmp/k would fail every proof while both name the
# same folder.
case "$KOSMOS_HOME" in
  */.|*/..|*/./*|*/../*)
    printf '\n  KOSMOS_HOME must not contain . or .. path components. Unset it and run again.\n\n' >&2
    exit 2
    ;;
esac
case "$KOSMOS_HOME" in
  *"
"*|*'"'*|*'$'*|*'`'*|*'\'*|*'}'*)
    printf '\n  KOSMOS_HOME contains a character (newline, quote, dollar, backtick, backslash or }) that would defeat the safety checks below. Unset it (or fix the home folder it defaults from) and run again.\n\n' >&2
    exit 2
    ;;
esac
# 🔑 A SANDBOXED KOSMOS_HOME SANDBOXES EVERY MACHINE-GLOBAL SURFACE, DERIVED
# HERE, ONCE, BEFORE ANYTHING READS THEM (#928, #934). The #883/#917
# derivation further down covers the three data roots, and only at the
# install path's start step; uninstall dispatches before it (#924's lesson)
# and these four never had one at all. So a walk that set only KOSMOS_HOME
# (Pete's convention) still repointed the operator's REAL ~/.local/bin/kosmos
# at the sandbox (#928, live incident: dangling after the tmp cleaner ate
# the target) and wrote its PATH line into the real ~/.zprofile, on every
# install AND on every auto-update tick, which re-runs this file.
# KOSMOS_HOME_APP_DIR is NOT derived: ~/Applications already carries the
# #226 ownership proof (a bundle is claimed only when its launcher names
# THIS KOSMOS_HOME), and sixteen harness scenarios exercise a fake
# HOME/Applications on purpose; deriving it moved every walk's icon and
# went red in the gate, measured 2026-08-26.
# Caller's explicit value always wins, matching every other ${VAR:-default}
# here. KOSMOS_APP_DIR is deliberately NOT derived: an override there means
# "no probing", and a sandboxed install must still exercise the
# /Applications ownership proof the harness tests with KOSMOS_APP_DIR= and
# a sandboxed KOSMOS_SYS_APP_DIR. AGENT_WORKFORCE_CLAUDE_BIN is NOT derived
# either, measured rather than reasoned: the carry (#548) runs Anthropic's
# installer, which lands at its own ~/.local/bin/claude, so a derived path
# made the installer unable to find what it had just installed (the gate's
# first leg went red). Claude Code is the person's real tool at its real
# path, not a sandbox surface; a harness pins it to a shared copy (#736).
# The default is computed the same way the
# two later copies compute it (slash-normalised like KOSMOS_HOME itself).
_kosmos_home_default="$(printf '%s' "$HOME/.local/share/kosmos" | /usr/bin/tr -s '/')"
_kosmos_home_default="${_kosmos_home_default%/}"
if [ "$KOSMOS_HOME" != "$_kosmos_home_default" ]; then
  [ -n "${KOSMOS_BIN_DIR:-}" ] || export KOSMOS_BIN_DIR="$KOSMOS_HOME/localbin"
  [ -n "${KOSMOS_PROFILE_FILE:-}" ] || export KOSMOS_PROFILE_FILE="$KOSMOS_HOME/zprofile"
fi
BIN_DIR="${KOSMOS_BIN_DIR:-$HOME/.local/bin}"
# ONE definition for the profile-wiring literals, used by the install
# wiring AND the uninstall sweep: two derivations of these strings is how
# the sweep silently stops matching what install wrote.
PATH_MARKER="# kosmos: PATH for the kosmos command (removed by --uninstall)"
PATH_LINE="export PATH=\"$BIN_DIR:\$PATH\""
# ⚠️ Overridable for the same reason the sources are: the sandboxed test of
# this installer must not write an app icon into the real Applications
# folders of the machine it runs on. Everything this script writes goes
# under a root the test can point somewhere disposable. When the override is
# set it is used VERBATIM -- no probing, no fallback -- so a sandbox stays a
# sandbox.
#
# ⚠️ WITHOUT the override, the icon goes to /Applications when this user can
# write there without a password, and only otherwise to ~/Applications.
# Measured on the first real clean-machine run (2026-08-13): the icon went
# to ~/Applications, the tester opened Finder's Applications (which shows
# /Applications), and concluded it "did not put it in my applications". For
# this installer's audience, an app that is not where people look does not
# exist. macOS gives admin users group write on /Applications, so the common
# case needs no password; the probe is an actual mkdir, not `-w`, because
# ACLs can make `-w` lie in both directions.
# ⚠️ THE ownership predicate, defined ONCE. Every rm -rf and every claim
# in this file is gated by this exact function; it was previously
# hand-assembled at a dozen sites in four different guard combinations,
# and every gap a review found was a site missing one guard the others
# had. It returns 0 only for a REAL directory bundle -- no symlink at
# the root, at Contents, at MacOS, or at the launcher leaf, because a
# link at any level would make the content check read a file the bundle
# does not own.
#
# ⚠️ TWO LAUNCHER SHAPES SHIP NOW (#677). The OLD bash-heredoc launcher
# carries this install's anchored token IN the executable itself
# (`:-<home>}"`, closing brace and quote included, so a prefix-related
# home cannot cross-match). The NEW compiled Swift binary is IDENTICAL
# across every install -- it is never re-baked per install -- so its
# anchor cannot live in the executable at all; it lives in the
# per-install Contents/Resources/kosmos-install.json instead, written
# with the same anchoring discipline (`"kosmosHome":"<home>"`, closing
# quote included). The old check runs first (cheap, and every install on
# disk before #677 is this shape); the new one is a fallback tried only
# when the old one does not match, never the reverse -- an old bundle is
# never asked to satisfy a proof it was never written to carry.
# /usr/bin/grep by absolute path throughout: this answer decides where
# rm -rf points, so it must not be answerable by whatever a user's PATH
# puts in front of grep (the same argument the write probe's /bin/mkdir
# records).
bundle_is_ours() {
  [ -d "$1" ] || return 1
  [ ! -L "$1" ] || return 1
  [ ! -L "$1/Contents" ] || return 1
  [ ! -L "$1/Contents/MacOS" ] || return 1
  [ ! -L "$1/Contents/MacOS/Kosmos" ] || return 1
  # A regular file, or no proof: a FIFO at the leaf would block the grep
  # forever (measured), and a hang with no sentence is the worst outcome
  # this file is written against. Same hardening class and cost as the
  # stage's bare mkdir.
  [ -f "$1/Contents/MacOS/Kosmos" ] || return 1
  /usr/bin/grep -qF ":-$KOSMOS_HOME}\"" "$1/Contents/MacOS/Kosmos" 2>/dev/null && return 0
  # The new-shape fallback: same symlink and regular-file discipline as
  # the executable above, applied to the config file instead, because a
  # link at this leaf would make the fallback read a file the bundle does
  # not own just as surely as a link at the executable would.
  [ ! -L "$1/Contents/Resources/kosmos-install.json" ] || return 1
  [ -f "$1/Contents/Resources/kosmos-install.json" ] || return 1
  /usr/bin/grep -qF "\"kosmosHome\":\"$KOSMOS_HOME\"" "$1/Contents/Resources/kosmos-install.json" 2>/dev/null
}

# SYS_APP_DIR is overridable ONLY so the harness can drive the probe AND its
# fallback against disposable directories -- a fallback that can only run
# where the primary works is untested by construction, and the probe's
# failure leg is exactly the one a standard (non-admin) user will live on.
# Test-only by contract, and SYMMETRIC by obligation: an install driven
# with this override must be uninstalled with the same value, or the
# sweep looks at the real /Applications and the sandboxed icon is
# orphaned.
SYS_APP_DIR="${KOSMOS_SYS_APP_DIR:-/Applications}"
# 🔑 THE ONE NAME FOR THE PERSON'S APPLICATIONS FOLDER (#721). Every reach the
# installer makes into ~/Applications goes through this: the icon write when
# the system folder is not writable, the retry, the migration block, the
# uninstall sweep. A walk that must keep HOME real (a signed-in Claude lives
# under it) sets KOSMOS_HOME_APP_DIR to a disposable folder and the operator's
# real ~/Applications is never touched; a sandboxed install once decorated it
# with a launcher into the sandbox (Pete, 2026-08-24 20:44). Third instance of
# one shape tonight, with KOSMOS_HOME_APP_DIR (migration) and
# KOSMOS_TMUX_BIN_PICKED (the picker): a seam named independently of the thing
# a real machine is recognised by. install.home-apps-seam.test.js keeps the
# class closed. Test-only by contract, like SYS_APP_DIR: #226 made that block skip under EITHER app-dir
# override so a run sandboxed only by KOSMOS_SYS_APP_DIR could never rm the REAL
# ~/Applications copy; the cost was that the harness could never exercise the
# migration at all (seven checks red since #442, 2026-08-23). A harness that
# NAMES a disposable folder here gets the block back, and only ever on that
# folder. Unset outside a harness: the block sees the real ~/Applications and
# the #226 gate still applies exactly as before.
HOME_APP_DIR="${KOSMOS_HOME_APP_DIR:-$HOME/Applications}"
# ⚠️ APP_DIR IS RESOLVED LAZILY, by the install path only, right before the
# icon is written. Resolving it here would run the write probe on EVERY
# invocation -- --uninstall, the unrecognised-flag refusal, the platform
# refusals -- and a run that refuses to do anything must not mutate
# /Applications. Until resolve_app_dir runs, APP_DIR carries the override
# or the safe per-user default, which is all the uninstall path needs.
APP_DIR="${KOSMOS_APP_DIR:-$HOME_APP_DIR}"
APP_OTHER_OWNER=no
APP_SKIP_ICON=no
APP_SKIP_REASON=""
APP_SYS_STALE=no
APP_SYS_FAILED=no
APP_HOME_FOREIGN=no
resolve_app_dir() {
  # The verbatim override is a sandbox: no probing, no fallback.
  [ -n "${KOSMOS_APP_DIR:-}" ] && { APP_DIR="$KOSMOS_APP_DIR"; return 0; }
  APP_DIR="$HOME_APP_DIR"
  # ⚠️ NEVER CLAIM A BUNDLE THIS INSTALL CANNOT PROVE IS ITS OWN. The
  # launcher bakes the installing user's KOSMOS_HOME as its default, so on
  # a Mac with two admin accounts, replacing the shared /Applications icon
  # would break the other account's working install, and every reinstall
  # would clobber the icon back and forth between them.
  #
  # ⚠️ POSITIVE PROOF, NOT ABSENCE OF DISPROOF. make_app begins with rm -rf
  # on its target, so claiming the path IS the destructive act. If ANYTHING
  # sits at the system path, it is claimed only on evidence: the launcher
  # line naming this KOSMOS_HOME, matched WITH its closing token
  # (`:-<home>}"`) so two homes in a prefix relationship cannot
  # cross-match. Everything else -- a third-party app that happens to be
  # named Kosmos, a half-written bundle, an unreadable launcher, a
  # different executable name -- diverts to the per-user folder, and the
  # icon step says so. (The first version keyed on the launcher FILE
  # existing, which made the install fail destructive exactly where the
  # uninstall below fails safe: a stranger's app was rm -rf'd while the
  # transcript printed success.)
  # -e OR -L, like every occupancy gate in this file: a symlink entry whose
  # target cannot be stat'd (dangling, or pointing into another user's
  # mode-700 home) fails -e alone, and the probe would then claim the slot
  # and rm -rf the link -- install failing destructive on exactly the
  # multi-account shape the uninstall below refuses. Measured in review.
  # A LINK ENTRY IS NEVER OURS: this installer never creates links, and
  # grep would follow one onto whatever it points at, claiming a user's
  # link to our own bundle and silently deleting it. Linkness decides
  # first; only a real directory earns the content check.
  if { [ -e "$SYS_APP_DIR/Kosmos.app" ] || [ -L "$SYS_APP_DIR/Kosmos.app" ]; } \
     && ! bundle_is_ours "$SYS_APP_DIR/Kosmos.app"; then
    APP_OTHER_OWNER=yes
    # ⚠️ THE DIVERT ITSELF NEEDS THE ALIASING GUARD. "Send the icon to the
    # per-user folder instead" is only an escape if the per-user folder is
    # a DIFFERENT folder: with ~/Applications symlinked to the system one,
    # writing "to the home folder" resolves straight back onto the foreign
    # bundle this branch just refused to claim, and make_app's opening
    # rm -rf would destroy it under a sentence saying it was left alone.
    # Same physical folder, or existing-but-unresolvable: no icon at all,
    # said honestly, fail closed. A home Applications folder that does not
    # exist yet cannot alias anything, so the divert proceeds and creates
    # it.
    if [ -e "$HOME_APP_DIR" ] || [ -L "$HOME_APP_DIR" ]; then
      _home_apps_phys="$(cd "$HOME_APP_DIR" 2>/dev/null && pwd -P)" || _home_apps_phys=""
      _sys_apps_phys="$(cd "$SYS_APP_DIR" 2>/dev/null && pwd -P)" || _sys_apps_phys=""
      # The two skip reasons get distinct sentences: "same folder" was
      # OBSERVED only on the equal-paths leg; the unresolvable legs know
      # merely that the folder could not be checked, and the sentence must
      # not claim more than that.
      if [ -n "$_home_apps_phys" ] && [ -n "$_sys_apps_phys" ]; then
        [ "$_home_apps_phys" = "$_sys_apps_phys" ] && { APP_SKIP_ICON=yes; APP_SKIP_REASON=same; }
      else
        APP_SKIP_ICON=yes
        APP_SKIP_REASON=unknown
      fi
    fi
    return 0
  fi
  # Old probe residue is cleaned before probing (the rmdir below is
  # best-effort, so a bizarre failure could have left one), which keeps
  # litter from ever accumulating; -f makes an unmatched glob harmless.
  # (Two accounts installing at the same instant could sweep each other's
  # live probe and fail one install with an unexplained transcript;
  # bounded, rare, and accepted rather than complicated away.)
  rm -rf "$SYS_APP_DIR"/.kosmos-write-probe.* 2>/dev/null || true
  # /bin/mkdir and /bin/rmdir by absolute path: the probe's answer decides
  # where an rm -rf will later point, so it must not be answerable by
  # whatever a user's PATH puts in front of mkdir.
  if /bin/mkdir "$SYS_APP_DIR/.kosmos-write-probe.$$" 2>/dev/null; then
    /bin/rmdir "$SYS_APP_DIR/.kosmos-write-probe.$$" 2>/dev/null \
      || rm -rf "$SYS_APP_DIR/.kosmos-write-probe.$$" 2>/dev/null || true
    APP_DIR="$SYS_APP_DIR"
  elif bundle_is_ours "$SYS_APP_DIR/Kosmos.app"; then
    # The probe FAILED on a machine where an earlier run of this install
    # already put an icon in the system folder (admin rights since lost,
    # folder since locked). The fresh icon goes to the home folder, and
    # the now-unreachable system icon is NAMED, or the user ends up with
    # two Kosmos icons and a sentence describing one.
    APP_SYS_STALE=probe
  fi
  return 0
}
# The port everything below names. Overridable for the sandboxed installer
# test; the app icon and the closing sentences bake in whatever was installed.
# 🔑 16180 RATHER THAN 4317, and the reason is neighbourhood rather than taste.
# 4317 is the OpenTelemetry OTLP/gRPC default and 4318 its HTTP sibling, so the
# people most likely to collide with Kosmos were the people already running
# agents -- exactly this product's audience. Josh picked 16180 (the golden
# ratio) and it checks out: nothing in the service registry, nothing clustered
# near it, and it is memorable enough to type.
#
# ⚠️ AND IT IS DELIBERATELY NOT IN 49152-65535, which was the tempting answer
# because no software ships a default there. MEASURED on macOS:
#     net.inet.ip.portrange.first: 49152
#     net.inet.ip.portrange.last:  65535
# That range IS the ephemeral pool the kernel hands out for outgoing
# connections, so a fixed listener in it would collide occasionally, randomly,
# and only sometimes -- an intermittent failure nobody can reproduce, which is
# worse than the deterministic one it replaced. The registered range is the
# quiet, stable part and that is where this sits.
#
# 📌 AN EXISTING INSTALL KEEPS THE PORT IT HAS. `kosmos` reads its own state, and
# KOSMOS_PORT still overrides everything here, so nothing moves under somebody
# who is already running.
# 🔑 PER ACCOUNT, NOT ONE VALUE FOR EVERY macOS USER ON THIS MACHINE (#910).
# Every account defaulting to the identical port is the entire reason a
# second macOS account's Kosmos loaded the first account's real agents:
# 127.0.0.1 is machine-wide, so `healthy()` always found account A's board
# first and account B's install never needed to bind a port of its own.
# uid 501 (the Setup Assistant's first created user account on every
# personal or family Mac -- macOS reserves anything below 500 for system
# accounts) is pinned to the LITERAL unchanged value: every real install
# today is hardcoded to exactly this, so the single most common Kosmos
# install on this planet changes zero observable bytes. Every other uid
# gets a deterministic, stable alternate -- `+1` on the modulo so it can
# never itself land back on 16180 by coincidence (uid % 4000 alone can be
# exactly 0). No probing, no persisted state: a pure function of `id -u`,
# so `kosmos start`/`stop`/`status` and this installer always agree with
# each other and with themselves, regardless of what any OTHER account's
# board happens to be doing at the moment. Moves together with the exact
# same formula in install/kosmos, install/pkg-scripts/postinstall, and
# native-app/main.swift.
_kosmos_uid="$(/usr/bin/id -u)"
if [ "$_kosmos_uid" = 501 ]; then
  _kosmos_default_port=16180
else
  _kosmos_default_port=$((16180 + 1 + (_kosmos_uid % 3999)))
fi
PORT="${KOSMOS_PORT:-$_kosmos_default_port}"
# The port is baked into the same unquoted launcher heredoc the
# KOSMOS_HOME character guard protects, so it gets the same posture:
# anything but digits is refused in a sentence (reproduced in review: a
# crafted KOSMOS_PORT ran a command at click time). The '' arm is
# unreachable belt (the :- default already replaced an empty value).
# Length-bounded BEFORE any numeric compare: test(1) overflows on huge
# digit strings and fails OPEN with raw shell errors (measured), so the
# case refuses empties, non-digits, leading zeros (they would be baked
# verbatim into the launcher URL), and anything over five digits, and
# only then is the in-range compare safe.
case "$PORT" in
  ''|*[!0-9]*|0*|??????*)
    printf '\n  KOSMOS_PORT must be a number from 1 to 65535, with no leading zeros. Unset it and run again.\n\n' >&2
    exit 2
    ;;
esac
if [ "$PORT" -gt 65535 ]; then
  printf '\n  KOSMOS_PORT must be a number from 1 to 65535. Unset it and run again.\n\n' >&2
  exit 2
fi
LOG_DIR="$KOSMOS_HOME/logs"
LOG="$LOG_DIR/install.log"

# ---- where the pieces come from --------------------------------------------
# ⚠️ BOTH SOURCES ARE OVERRIDABLE, and that is what makes the clean-machine test
# possible. On a release these fetch from the published URL. For the first run on
# a never-touched Mac we want to test the INSTALLER, not the CDN, so
# KOSMOS_TMUX_SRC and KOSMOS_SRC can point at local files carried over on a
# thumb drive. Same code path, one variable different.
KOSMOS_RELEASE_BASE="${KOSMOS_RELEASE_BASE:-https://installkosmos.com/dist}"

# ⚠️ EVERY DOWNLOAD IS CHECKSUM-VERIFIED before anything is extracted. The
# build publishes a .sha256 next to each tarball; a mismatch, a truncated
# download, or a missing checksum file all refuse in a sentence.
# ⚠️ WHAT THIS IS AND IS NOT: the checksum travels from the SAME origin over
# the SAME channel as the tarball, so it catches corruption, truncation and
# a half-updated CDN -- it adds nothing against a compromised origin, which
# already served this very script. Signing with a key that does not travel
# beside the artifact is the upgrade, and is on the launch security list.
# ⚠️ shasum, not sha256sum: macOS ships shasum, and this is the user path
# where nothing beyond a clean Mac may be assumed.
verify_download() {
  local file="$1" url="$2" shaurl="${3:-$2.sha256}" want got
  curl -fsL -m 30 "$shaurl" -o "$file.sha256" 2>/dev/null || {
    info "the download could not be verified (its verification file is missing)."
    info "This usually means the download site is mid-update. Wait a minute, then paste the install line again."
    return 1
  }
  want="$(awk '{print $1; exit}' "$file.sha256")"
  got="$(shasum -a 256 "$file" | awk '{print $1}')"
  rm -f "$file.sha256"
  if [ -z "$want" ] || [ "$want" != "$got" ]; then
    info "the download did not arrive intact."
    info "Paste the install line again; if it keeps happening, the download site may be mid-update."
    return 1
  fi
  return 0
}

# A HEAD probe first, and a one-byte ranged GET before refusing: some static
# origins reject HEAD (405) while serving GET fine, and "check your internet
# connection" for a working connection is the wrong sentence.
# ⚠️ A STATUS CODE CANNOT ANSWER "IS THE DOWNLOAD THERE". This used to accept
# any response and therefore accepted every url ON AN HTTP ORIGIN WHOSE 404 PAGE
# ANSWERS A RANGE REQUEST, including names that cannot exist. (Not literally
# every url: a missing `file://` path already failed, rc 37, and there is an arm
# for it.) The range arm asks a web server for the first byte of its own 404
# page and gets `206 text/html, 1 byte`, which is a success. Measured
# 2026-08-31 against a deliberately impossible name, which PASSED.
#
# The cost was not a wrong answer, it was SILENCE. The guard could never fire, so the sentence written for exactly this case ("could not reach
# the download ... it is safe to re-run") was dead code, and a person whose
# download was missing met a bare curl failure with no guidance instead. Every
# caller here fetches a TARBALL, so the answer is knowable: assert the content
# type, and an error page can no longer impersonate a download.
#
# 🛑 A FIX HERE IS ONLY PROVEN BY A URL THAT CANNOT EXIST RETURNING FALSE. The
# broken version passed on real files too, so "it still finds the tarball" is
# not evidence of anything. See install.reachable-1662.test.js, which asserts
# both arms against a local server.
_reachable_is_download() {
  # $1 = curl's exit status, $2 = the content-type it reported.
  #
  # 🛑 REFUSE WHAT IS POSITIVELY TEXTUAL; DO NOT DEMAND A KNOWN BINARY. An
  # allowlist of binary types looks stricter and is wrong here, because the
  # cost is asymmetric: a false YES only means this pre-check did not help and
  # curl fails a few lines later with its own error, which is the behaviour
  # before this guard existed. A false NO stops the install outright behind
  # "Check your internet connection", which is worse than the bug it is for.
  #
  # ⚠️ THAT ASYMMETRY HOLDS AT TWO OF THE THREE CALL SITES, NOT ALL THREE, and
  # saying it unconditionally would be false. At the `TARGET_VERSION` probe
  # this predicate is an EXISTENCE TEST, not an abort guard: a false NO there
  # does not stop the install, it falls to the next branch. Downstream
  # `verify_download` still checks the sha and the version refusal still fires.
  #
  # 🛑 AND THE COST OF THAT FALL-THROUGH IS SMALL FOR EVERY NETWORK INSTALL,
  # which is the point most easily got wrong here.
  # `BUST=yes` is set for any http/https base and
  # `install_kosmos` runs after that, so the fallback is the `elif` arm, which
  # fetches the cache-BUSTED `kosmos-$ARCH.tar.gz?v=...`. A cache treats that as
  # a fresh resource, so there is no collision to inherit. The bare unversioned
  # name is reached only when BUST is empty, i.e. `file://` bases, which have no
  # cache to collide with in the first place. So a false NO here costs the
  # version-named artifact, not a stale one.
  #
  # ⚠️ AND AN ALLOWLIST BREAKS THE PROJECT'S OWN INSTALL GATE. `curl` on a
  # `file://` URL succeeds and reports an EMPTY content-type (measured: a real
  # gzip gives content_type=[] with exit 0), and tools/test-install.sh drives
  # the whole release path over `file://` on purpose. An allowlist refuses a
  # genuine tarball there and aborts the download path.
  #
  # ⚠️ Media types are case-insensitive (RFC 9110 section 8.3), so the compare
  # is lowercased. The case that matters is a CAPITALISED TEXTUAL type being
  # refused (`Text/HTML`), not a capitalised binary one being accepted: unknown
  # types are accepted anyway, so an `Application/GZIP` arm proves nothing.
  #
  # 🛑 `text/html` AND NOT `text/*`, DELIBERATELY. `text/plain` is nginx's
  # compiled-in `default_type`, so a mirror that has not mapped `.gz` serves a
  # genuine tarball as `text/plain`. Refusing it would block that install
  # behind "Check your internet connection" -- the exact false NO this design
  # is built to avoid, and `KOSMOS_RELEASE_BASE` is overridable, so a mirror is
  # a real case rather than a hypothetical one. A plain-text error page passing
  # is the harmless direction: curl fails a few lines later with its own error.
  #
  # The exit status is checked FIRST and separately, because an empty
  # content-type from a FAILED connection must not read the same as an empty
  # one from a local file that is genuinely there.
  #
  # 📌 THIS IS DELIBERATELY LOOSER THAN `serves_gzip()` in
  # tools/kosmos-artifact-check.sh, which requires the type to CONTAIN gzip.
  # They judge the same header for opposite stakes, so they should not match:
  # that one gates a RELEASE, where a false NO safely blocks a bad cut and a
  # false YES ships one; this one gates a PERSON'S INSTALL, where a false NO
  # is an installer that refuses to run. Tightening this to match it would
  # reintroduce the file:// break above.
  [ "$1" = 0 ] || return 1
  # /usr/bin/tr, matching the six other ABSOLUTE `tr` call sites in this file (a
  # seventh, at the `_pids` line, is bare). The reason is
  # narrow and worth stating so nobody generalises it: the design is fail-open,
  # so a `tr` that did not resolve would empty the substitution, match no arm,
  # and silently accept EVERY type. That is the harmless direction by this
  # predicate's own asymmetry, but it would make the guard invisible rather
  # than noisy. It is NOT a general absolute-path policy: `curl` two lines
  # below is bare, as it is everywhere else in this file.
  case "$(printf '%s' "$2" | /usr/bin/tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 'abcdefghijklmnopqrstuvwxyz')" in
    text/html*|application/xhtml*|application/json*|application/*+json*|application/xml*|application/*+xml*|text/xml*) return 1 ;;
  esac
  return 0
}

# ⚠️ THE NAME IS WIDER THAN THE CONTRACT. This answers "is this a NON-TEXTUAL
# DOWNLOAD", not "is this URL reachable": a perfectly reachable JSON or XML URL
# is refused on purpose. Every caller here fetches a tarball, so that is the
# question they are asking -- but do not reuse this for a general reachability
# test. `latest.json` is fetched by bare curl further down for exactly that
# reason, and routing it through here would refuse it.
reachable() {
  # HEAD first; the range GET is the fallback for hosts that refuse HEAD.
  # A 404 page answers a range request with 206 and its own HTML body, so the
  # status alone cannot tell a download from an error page: the type must be
  # judged too, on both arms.
  # 🛑 `cmd && rc=0 || rc=$?`, NOT a bare assignment. This file runs under
  # `set -euo pipefail`, set near the top of this file, where a plain
  # `_r_ct=$(curl …)` is an UNPROTECTED SIMPLE COMMAND: a failing HEAD probe aborts the whole shell
  # before the range-GET fallback can run. The pre-#1662 form happened to be
  # safe because `curl … && return 0` was shielded by the `&&`.
  # Both shapes were measured under `set -euo pipefail`; the transcript is in
  # .claude/plans/reachable-1662.md rather than here.
  # Latent rather than live today, because -e is suspended at all three call
  # sites: the two guards in fetch_tmux and install_kosmos capture the status
  # with `|| _r_why=$?`, and the probe that picks the versioned tarball is the
  # right side of a `&&`. (This sentence used to describe the guards as
  # `if ! reachable`, the shape THIS branch replaced. The conclusion held and
  # the description had rotted, which is the failure the paragraph below is
  # about.) It is still a trap,
  # and it lands exactly on the fallback's reason for existing: a 405 on HEAD.
  # The call sites are named by their surrounding code above rather than by
  # position, because nothing checks a line number in a comment.
  local _r_ct _r_rc _r_out _r_code _r_answered
  # 🛑 ACCUMULATED ACROSS BOTH PROBES, NEVER OVERWRITTEN. The second probe used
  # to clobber the first probe's status, so a HEAD that got a definite answer
  # (a hard 404, or a 200 carrying HTML) followed by a range GET that failed to
  # COMPLETE (reset, DNS blip, an origin that drops the second connection) left
  # code 000 with a non-zero rc, and the caller told the user to check a
  # connection about a server that had demonstrably answered. Same wrong-sentence
  # class this card removes, pointed the other way.
  #
  # 📌 `if` rather than `{ …; } && _r_answered=1` is READABILITY ONLY, not
  # safety. An AND-OR list is EXEMPT from `set -e` whether or not the left side
  # fails, measured on /bin/sh with a control. This file uses that shape 14
  # times, including the `= 63` remap in the range-GET arm below, so do not
  # "fix" them. (Plan file has the measurement.) Named by its surrounding code
  # rather than by a distance, per the rule stated on the `local` declaration
  # that opens this function: the old reference said "twenty lines" and had
  # become 82. I then wrote "twelve lines above" for the rule itself and that was
  # wrong too, by three. A distance in a comment is wrong the moment anyone edits
  # above it, which is the whole reason the rule exists.
  _r_answered=0
  # %{http_code} FIRST because a content type contains spaces ("text/html;
  # charset=utf-8") and a status code never does, so the split is unambiguous.
  _r_out=$(curl -fsIL -m 15 -o /dev/null -w '%{http_code} %{content_type}' "$1" 2>/dev/null) && _r_rc=0 || _r_rc=$?
  _r_code=${_r_out%% *}; _r_ct=${_r_out#* }
  case "$_r_code" in ''|*[!0-9]*) _r_code=0 ;; esac
  case "$_r_out" in *' '*) ;; *) _r_ct='' ;; esac
  # 🛑 A METHOD REFUSAL IS NOT AN ANSWER ABOUT THE ARTIFACT. 405 and 501 mean
  # "I do not do HEAD", which says nothing about whether the file exists, so
  # they must not set _r_answered here. Without this, an origin that refuses
  # HEAD and whose range GET then fails to COMPLETE (reset, DNS blip) got
  # status 2 and was told to check the address, when the truth is a transient
  # connection failure that wants "it is safe to re-run". That is this card's
  # own wrong-sentence defect aimed at the shape the fallback exists for.
  # A 405 followed by a SUCCESSFUL range GET is unaffected: the range arm sets
  # the flag on its own rc.
  # 🛑 rc 37 GETS ITS OWN STATUS, IT IS NOT "THE SERVER ANSWERED". 37 is
  # FILE_COULDNT_READ_FILE: a `file://` path that is absent or unreadable. There
  # is no server, no release and no network, so folding it into status 2 printed
  # two false causes at a reader whose only true one is the path. Three separate
  # reviewers found that sentence before it was split out.
  [ "$_r_rc" = 37 ] && return 3
  if [ "$_r_rc" = 0 ]; then
    _r_answered=1
  elif [ "$_r_code" -ge 400 ] && [ "$_r_code" != 405 ] && [ "$_r_code" != 501 ]; then
    _r_answered=1
  fi
  _reachable_is_download "$_r_rc" "$_r_ct" && return 0
  # 📌 This arm also runs when HEAD SUCCEEDED with a textual type, where the
  # pre-#1662 code reached it only after a HEAD failure. Kept because refusing
  # on a single mis-typed HEAD would be a false NO, and there is an arm
  # asserting it buys that.
  #
  # ⚠️ THE COST, MEASURED ON BOTH ARMS. It is NOT the 30s hung-origin
  # case: measured, the pre-#1662 predicate also ran both probes to full
  # timeout there (HEAD times out, the `&&` falls through, the range GET runs),
  # old 30s NO and new 30s NO, identical. And NO for a host that cannot be
  # reached is the CORRECT answer, not a false one.
  #
  # The genuinely new cost is one extra request after a textual HEAD, normally
  # fast. The real residual is narrower and worth naming: against an origin
  # that IGNORES Range and answers 200 with the whole body, that request
  # streams the tarball, and on a slow enough link `-m 15` expires and the
  # predicate answers NO on a genuine download. That needs a mis-typed HEAD AND
  # a Range-ignoring origin AND a slow link together. It is untested here: a
  # faithful test would have to burn the full 15s timeout, which buys one
  # narrow arm at the price of a slow and timing-dependent suite.
  # --max-filesize bounds the residual named above: an origin that ignores
  # Range answers with the WHOLE body, and without a cap this probe would
  # stream a 48MB tarball into /dev/null until -m 15 expired.
  #
  # ⚠️ THAT BOUND IS CURL-VERSION DEPENDENT, SO DO NOT READ IT AS A GUARANTEE.
  # The macOS manpage says "the transfer does not start", i.e. the decision is
  # made from an ANNOUNCED content-length; and curl only began aborting an
  # already-running transfer in 8.4.0. tools/macos-floor declares this
  # installer's floor as 13.5, which ships curl 8.1.x. So against an origin that
  # omits content-length, on the floor OS, the residual is bounded by -m 15 and
  # not by this cap. Measured on curl 8.7.1 the cap DOES stop a length-less
  # transfer mid-flight, which is why the test arm for that shape asserts the
  # VERDICT and deliberately does not pin a byte count: the count is the part
  # that legitimately differs across versions.
  #
  # ⚠️ THE HTML-ON-63 REFUSAL ALSO RESTS ON A CURL VERSION, and this comment is
  # scrupulous about that everywhere else, so it should be here too. Refusing a
  # capped HTML body needs curl to still REPORT a content-type alongside exit
  # 63. Measured on 8.7.1 it does. On the 13.5 floor's curl 8.1.x the abort
  # happens before the transfer starts, and if content_type is empty there that
  # arm flips NO to YES. The shipped-code direction is the harmless one, a false
  # YES that curl catches a few lines later; the cost is a red suite on a
  # floor-OS runner rather than a broken install.
  #
  # 🛑 AND EXIT 63 MUST BE TREATED AS A SUCCESSFUL FETCH. Getting this wrong is
  # a REGRESSION, not a missed improvement. curl exits 63 when the
  # cap is hit, `_reachable_is_download` saw non-zero, and a GENUINE download
  # from a HEAD-refusing Range-ignoring origin was refused with "could not
  # reach the download". Measured against exactly that shape serving a real
  # 5MB body: capped NO, uncapped YES. That is the false-NO direction this
  # predicate's whole design says is the worst outcome.
  #
  # ⭐ A body that EXCEEDS the cap is affirmatively NOT a small error page, so
  # 63 is evidence FOR a download rather than against one. curl still reports
  # the content-type on 63 (measured, for both `application/gzip` and
  # `text/html`), so mapping it to 0 hands the decision to the type rule rather
  # than short-circuiting it: a 5MB gzip is accepted, a 5MB HTML page is still
  # refused.
  _r_out=$(curl -fsL -r 0-0 -m 15 --max-filesize 1048576 -o /dev/null -w '%{http_code} %{content_type}' "$1" 2>/dev/null) && _r_rc=0 || _r_rc=$?
  [ "$_r_rc" = 63 ] && _r_rc=0
  _r_code=${_r_out%% *}; _r_ct=${_r_out#* }
  case "$_r_code" in ''|*[!0-9]*) _r_code=0 ;; esac
  case "$_r_out" in *' '*) ;; *) _r_ct='' ;; esac
  # 📌 NO 405/501 CARVE-OUT HERE, DELIBERATELY, and the asymmetry with the HEAD
  # arm is the point. On HEAD a 405 is about the METHOD and says nothing about
  # the artifact. On the range GET the request named the artifact, so any 4xx IS
  # an answer about it: a 416 from a zero-length object means the file exists and
  # is unusable, which is what status 2 says. If a future edit makes the two arms
  # match "for consistency", it will be re-introducing the bug the HEAD carve-out
  # fixed, backwards.
  [ "$_r_rc" = 37 ] && return 3
  if [ "$_r_rc" = 0 ] || [ "$_r_code" -ge 400 ]; then _r_answered=1; fi
  _reachable_is_download "$_r_rc" "$_r_ct" && return 0
  # 🛑 TWO DIFFERENT FAILURES, TWO DIFFERENT STATUSES, because they need
  # different sentences. rc 0 here means the origin ANSWERED and served
  # something textual. Anything else means the request did not complete at all.
  #
  # ⚠️ STATUS 2 HAS TWO CAUSES AND THIS LAYER CANNOT TELL THEM APART, so the
  # sentence must not pick one. A half-published CDN and an intercepting network
  # (captive portal, corporate proxy block page, ISP NXDOMAIN redirect) BOTH
  # answer 200 with text/html, which is byte-for-byte the same signature here.
  # An earlier version of this named only the CDN and told portal users to wait
  # for a release that was already published, which is the same class of wrong
  # advice as the "check your connection" it replaced, pointed the other way.
  #
  # ⚠️ Every caller uses `!`, `&&` or a `!= 0` test, all of which treat 1 and 2
  # identically, so this changes no control flow anywhere. It only lets a caller
  # pick its sentence.
  [ "$_r_answered" = 1 ] && return 2
  # 🛑 AN HTTP ERROR IS ALSO THE SERVER ANSWERING, AND rc ALONE MISSES IT. `-f`
  # makes curl exit non-zero on a 4xx even though the request COMPLETED, so
  # testing rc covered only origins whose error page answers 2xx (this site's
  # 404 replies 206 with its own HTML, which is why the arms passed). S3, R2 and
  # GitHub Releases return a HARD 404 for a not-yet-published object, the most
  # common half-published shape, and those fell through to "check your internet
  # connection". Measured: a GitHub Releases 404 gives exit 56, http_code 404.
  return 1
}

# One copy of the refusal, because it carries four lines of user-facing text and
# now branches three ways. It was duplicated verbatim in fetch_tmux and
# install_kosmos, policed by a byte-identity assertion in the suite; a helper
# makes that assertion unnecessary rather than load-bearing, and a wording edit
# can no longer land in one caller and not the other.
#
# $1 = the status reachable() returned, $2 = the url.
_reachable_refuse() {
  case "$1" in
    3)
      info "the download at $2 is not there"
      info "That path does not exist or cannot be read. Check the address it is installing from."
      ;;
    2)
      # NOT "could not reach": the origin answered. Saying both contradicts itself.
      info "the download at $2 is not usable"
      info "The address it is downloading from did not give an installable file."
      info "The release may still be publishing, something on your network may be intercepting the request, or the address may be wrong."
      info "Try again in a few minutes; if it keeps happening, check the address."
      ;;
    *)
      info "could not reach the download at $2"
      info "Check your internet connection and paste the install line again; it is safe to re-run."
      ;;
  esac
}

# ⚠️ FETCHED INTO A FRESH STAGE AND SWAPPED, never merged over what is there.
# Merging an update over an old tree keeps files the new version deleted, and
# a half-failed copy leaves a tree that LOOKS installed. The swap means the
# destination is only ever a complete old version or a complete new one.
# ⚠️ Sweep only the DEAD runs' stages (#236). The wildcard swept every
# sibling stage, including one a concurrently RUNNING install was mid-download
# into -- two overlapping installs (the install suite, or two accounts on one
# Mac) destroyed each other's staging. Each stage ends in the pid that made
# it; a stage whose pid is alive belongs to someone and is left alone. A pid
# that is not a number is old junk and goes. PID reuse can spare a leftover
# until the next sweep, which costs disk for a day, not a download.
sweep_dead_stages() {
  for _stg in "$@"; do
    [ -e "$_stg" ] || continue
    _spid="${_stg##*.}"
    case "$_spid" in
      *[!0-9]*|'') rm -rf "$_stg" 2>/dev/null || true ;;
      *) kill -0 "$_spid" 2>/dev/null || rm -rf "$_stg" 2>/dev/null || true ;;
    esac
  done
}

fetch_tmux() {
  local dest="$1"
  local stage="$dest.stage.$$"
  # Sweep leftovers from interrupted PREVIOUS attempts (each run stages
  # under a fresh $$, so an interrupt -- not a failure path -- accumulates
  # ~130MB per Ctrl-C otherwise, invisibly, forever). Dead runs only (#236).
  sweep_dead_stages "$dest".stage.*
  # ⚠️ EVERY failure path removes the stage. Returning without cleanup left a
  # partial stage directory behind per attempt (a new $$ each run), so a
  # flaky connection accumulated half-downloads in the user's install.
  rm -rf "$stage"
  mkdir -p "$stage" || { rm -rf "$stage"; return 1; }
  if [ -n "${KOSMOS_TMUX_SRC:-}" ]; then
    info "using local copy: $KOSMOS_TMUX_SRC"
    [ -d "$KOSMOS_TMUX_SRC" ] || { rm -rf "$stage"; return 1; }
    cp -R "$KOSMOS_TMUX_SRC/." "$stage/" || { rm -rf "$stage"; return 1; }
  else
    # The version-tied query is the same cache-buster the kosmos fetch
    # carries: one URL across releases invites a cache to answer with
    # the past. tmux changes rarely, which makes a stale copy HARDER to
    # notice, not safer.
    local url="$KOSMOS_RELEASE_BASE/tmux-$ARCH.tar.gz" shaurl=""
    if [ -n "${BUST:-}" ]; then
      url="$KOSMOS_RELEASE_BASE/tmux-$ARCH.tar.gz?v=${TARGET_VERSION:-$$}"
      shaurl="$KOSMOS_RELEASE_BASE/tmux-$ARCH.tar.gz.sha256?v=${TARGET_VERSION:-$$}"
    else
      shaurl="$url.sha256"
    fi
    # A reachability probe first, so the two failures a launch-day install
    # actually hits (no network, a half-published CDN) refuse in a sentence
    # instead of a curl error code. The real download keeps its progress
    # bar, which lives on stderr and cannot be silenced without losing it.
    local _r_why=0; reachable "$url" || _r_why=$?
    if [ "$_r_why" != 0 ]; then
      _reachable_refuse "$_r_why" "$url"
      rm -rf "$stage"; return 1
    fi
    info "downloading from $url"
    # ⚠️ Progress is ON. `curl -fsSL` is silent, and several minutes of nothing
    # is the failure this whole file is written against.
    curl -fL --progress-bar "$url" -o "$stage/tmux.tar.gz" || { rm -rf "$stage"; return 1; }
    verify_download "$stage/tmux.tar.gz" "$url" "$shaurl" || { rm -rf "$stage"; return 1; }
    tar -xzf "$stage/tmux.tar.gz" -C "$stage" || { rm -rf "$stage"; return 1; }
    rm -f "$stage/tmux.tar.gz"
  fi
  [ -f "$stage/bin/tmux" ] && [ -x "$stage/bin/tmux" ] || { rm -rf "$stage"; return 1; }

  # ⚠️ VERIFY THE THING WE JUST PLACED, rather than assuming the copy worked.
  # An arm64 binary with a broken signature does not run at all, and the failure
  # is silent and baffling. Better to say so here than to have the board come up
  # empty later with no explanation.
  if ! codesign -v "$stage/bin/tmux" 2>/dev/null; then
    info "the copy of tmux did not arrive intact"
    rm -rf "$stage"
    return 1
  fi
  # ⚠️ AND VERIFY IT RUNS ON THIS MAC, the same check the Node runtime gets
  # at build time. A binary built against a newer macOS than this one loads
  # nothing and says nothing; without this line the first symptom is a board
  # that reads every agent as unknown, which nobody would ever trace to dyld.
  if ! "$stage/bin/tmux" -V >/dev/null 2>&1; then
    info "the copy of tmux will not run on this computer."
    info "That is a problem with the download itself, not with your Mac or your network; trying again will not fix it. We need to publish a corrected download."
    rm -rf "$stage"
    return 1
  fi
  rm -rf "$dest" || { rm -rf "$stage"; return 1; }
  mv "$stage" "$dest" || { rm -rf "$stage"; return 1; }
  return 0
}

install_kosmos() {
  local dest="$1"
  local stage="$dest/.kosmos.stage.$$"
  sweep_dead_stages "$dest"/.kosmos.stage.*
  rm -rf "$stage"
  mkdir -p "$stage" || { rm -rf "$stage"; return 1; }
  local from_network=no
  if [ -n "${KOSMOS_SRC:-}" ]; then
    info "using local copy: $KOSMOS_SRC"
    [ -d "$KOSMOS_SRC" ] || { rm -rf "$stage"; return 1; }
    cp -R "$KOSMOS_SRC/." "$stage/" || { rm -rf "$stage"; return 1; }
  else
    from_network=yes
    # ⚠️ THE BYTES MUST BE THE POINTER'S VERSION. The plain name is one
    # URL across every release, so any cache between this Mac and the
    # host can satisfy it with LAST release's tarball and its matching
    # checksum, and the swap below would then install old bytes while
    # reporting success (measured on Josh's machine, 2026-08-24: a
    # completed update log over a disk still holding the prior version).
    # The versioned name cannot collide across releases; where it is not
    # published yet, the plain name is fetched with a version-tied
    # cache-busting query, which a cache treats as a fresh resource.
    local url="" shaurl=""
    if [ -n "${TARGET_VERSION:-}" ] && reachable "$KOSMOS_RELEASE_BASE/kosmos-$TARGET_VERSION-$ARCH.tar.gz"; then
      url="$KOSMOS_RELEASE_BASE/kosmos-$TARGET_VERSION-$ARCH.tar.gz"
      shaurl="$url.sha256"
    elif [ -n "${BUST:-}" ]; then
      url="$KOSMOS_RELEASE_BASE/kosmos-$ARCH.tar.gz?v=${TARGET_VERSION:-$$}"
      shaurl="$KOSMOS_RELEASE_BASE/kosmos-$ARCH.tar.gz.sha256?v=${TARGET_VERSION:-$$}"
    else
      url="$KOSMOS_RELEASE_BASE/kosmos-$ARCH.tar.gz"
      shaurl="$url.sha256"
    fi
    local _r_why=0; reachable "$url" || _r_why=$?
    if [ "$_r_why" != 0 ]; then
      _reachable_refuse "$_r_why" "$url"
      rm -rf "$stage"; return 1
    fi
    info "downloading from $url"
    # kosmos#3233 (the open half of #920): emit determinate download progress
    # for the install page. BEST-EFFORT and fully isolated from the download --
    # every step below is guarded so a failure here can neither abort nor alter
    # the curl, its checksum gate, or its error handling. A file:// page cannot
    # fetch, so we write a tiny JS file (window.__kosmosInstallProgress) the page
    # re-includes; there is NO server and NO runtime dependency (a server would
    # need node, which arrives WITH this bundle, or /usr/bin/python3, which is
    # only the Command Line Tools stub on a fresh box -- see the note near the
    # settings verify below). The page shows the SHAPE of the wait (a determinate
    # bar), never a megabytes figure (#920's deliberate stance).
    _kp_dir="$HOME/Library/Caches/Kosmos"
    _kp_js="$_kp_dir/install-progress.js"
    # Guarded assignment: under this file's set -euo pipefail a failing HEAD (a timeout,
    # a 4xx/5xx under -f, a host that refuses HEAD) propagates through pipefail as the
    # pipeline's status, so a bare assignment would abort the install here. Fall back to
    # an empty total -> the page keeps its indeterminate swoosh. Same idiom the
    # reachable()/_kosmos_data_root() comments document for this file.
    # -m 5 (not 15): reachable() a few lines up already round-tripped this exact $url and
    # succeeded, so this HEAD answers in ~1 RTT in practice; the short cap bounds the
    # pathological "answered the probe, hangs on the second HEAD" host so it cannot add a
    # visible stall before the download starts.
    _kp_total=$(curl -fsIL -m 5 "$url" 2>/dev/null \
      | awk 'tolower($1)=="content-length:"{v=$2} END{gsub(/[^0-9]/,"",v);print v}') || _kp_total=""
    case "$_kp_total" in ''|*[!0-9]*) _kp_total="";; esac
    _kp_emit() {  # $1 = phase; best-effort, always returns 0
      [ -d "$_kp_dir" ] || mkdir -p "$_kp_dir" 2>/dev/null || return 0
      _kp_b=$(stat -f%z "$stage/kosmos.tar.gz" 2>/dev/null || echo 0)
      case "$_kp_b" in ''|*[!0-9]*) _kp_b=0;; esac
      # case, not `[ -n ] && ...`: the AND-list returns 1 when total is empty (the
      # common no-content-length case), which under set -e -- active inside the
      # background watcher subshell -- would abort the watcher before the write.
      _kp_t=null; case "$_kp_total" in ?*) _kp_t="$_kp_total";; esac
      _kp_tmp="$_kp_js.$$.tmp"
      # `|| true` so a failed write cannot abort under set -e either: the function's
      # contract is best-effort and always returns 0, so it can never take the install down.
      printf 'window.__kosmosInstallProgress={bytes:%s,total:%s,phase:"%s",ts:%s};\n' \
        "$_kp_b" "$_kp_t" "$1" "$(date +%s 2>/dev/null || echo 0)" > "$_kp_tmp" 2>/dev/null \
        && mv -f "$_kp_tmp" "$_kp_js" 2>/dev/null || true
      return 0
    }
    _kp_sentinel="$stage/.kp-active"
    _kp_ppid=$$
    : > "$_kp_sentinel" 2>/dev/null || true
    # Bounded watcher: exits when the sentinel is removed (normal teardown below) OR when
    # its parent -- this installer -- has died, so a hard `kill -9` of setup.sh cannot
    # orphan a process that rewrites install-progress.js once a second forever. kill -0
    # tests liveness without signalling; $_kp_ppid is captured before the fork (in a
    # backgrounded ( ) subshell $$ is the parent's PID, so it is captured explicitly).
    ( while [ -f "$_kp_sentinel" ] && kill -0 "$_kp_ppid" 2>/dev/null; do _kp_emit downloading; sleep 1; done ) &
    _kp_watcher=$!
    curl -fL --progress-bar "$url" -o "$stage/kosmos.tar.gz" \
      || { rm -f "$_kp_sentinel" 2>/dev/null || true; kill "$_kp_watcher" 2>/dev/null || true; rm -rf "$stage"; return 1; }
    # Guarded teardown: killing an already-exited watcher, and wait returning the
    # watcher's 143 (128+SIGTERM), are non-zero trailing simple commands that would
    # abort under set -e. || true keeps this isolation INTRINSIC, not merely inherited
    # from the `install_kosmos ... || die` call site that suspends errexit today.
    rm -f "$_kp_sentinel" 2>/dev/null || true; kill "$_kp_watcher" 2>/dev/null || true; wait "$_kp_watcher" 2>/dev/null || true
    _kp_emit downloaded
    verify_download "$stage/kosmos.tar.gz" "$url" "$shaurl" || { rm -rf "$stage"; return 1; }
    _kp_emit installing
    tar -xzf "$stage/kosmos.tar.gz" -C "$stage" || { rm -rf "$stage"; return 1; }
    rm -f "$stage/kosmos.tar.gz"
  fi
  # ⚠️ THE STAGE IS VERIFIED, THEN SWAPPED. On the update path the old
  # bundle already satisfies checks against $dest, so a failed copy used to
  # read as a successful update: the check must look at what just arrived,
  # never at what was already there. Only the bundle's three components are
  # replaced; tmux/, logs/ and the pidfile are the machine's own state.
  # ⚠️ Three renames, not one, so there IS a small window where an interrupt
  # leaves part-old, part-new -- stated rather than claimed away. The board
  # is stopped during the swap, every rename is same-filesystem, and the
  # recovery is the installer's own re-run, which `kosmos start` names when
  # the tree is incomplete.
  [ -f "$stage/bin/kosmos" ] && [ -x "$stage/bin/kosmos" ] || { rm -rf "$stage"; return 1; }
  [ -f "$stage/runtime/bin/node" ] && [ -x "$stage/runtime/bin/node" ] || { rm -rf "$stage"; return 1; }
  [ -f "$stage/app/server.js" ] || { rm -rf "$stage"; return 1; }
  [ -f "$stage/app/web/index.html" ] || { rm -rf "$stage"; return 1; }
  # The Plus connector (#583) rides in the bundle; a Kosmos without it installs
  # fine and then cannot turn Plus on, so a missing one is a broken download.
  [ -f "$stage/app/bin/kosmos-tunnel" ] && [ -x "$stage/app/bin/kosmos-tunnel" ] || { rm -rf "$stage"; return 1; }
  # The runtime must RUN here, the same probe the tmux bundle gets: a
  # binary that will not load fails silently and baffling, and the floor
  # gate upstream makes that unlikely, not impossible.
  if ! "$stage/runtime/bin/node" --version >/dev/null 2>&1; then
    info "the runtime will not run on this computer"
    rm -rf "$stage"
    return 1
  fi
  local part
  for part in bin app runtime; do
    rm -rf "$dest/$part" || { rm -rf "$stage"; return 1; }
    mv "$stage/$part" "$dest/$part" || { rm -rf "$stage"; return 1; }
  done
  # The bundle's VERSION record rides along (what shipped, traceable to a
  # binary); optional so an older bundle without one still installs.
  if [ -f "$stage/VERSION" ]; then
    rm -f "$dest/VERSION"
    mv "$stage/VERSION" "$dest/VERSION" || { rm -rf "$stage"; return 1; }
  fi
  rm -rf "$stage"
  # 🛑 THE READ-BACK IS THE PROOF. Every claim above is about what this
  # run DID; this is the only line that looks at what the destination
  # HOLDS. A landed version that differs from the run's target means some
  # cache served old bytes whatever the transport, and the one honest
  # outcome is failure in a sentence, never "installed ... done" over the
  # previous release. Unknown landed version with a known target is
  # reported, not fatal: an older bundle without the field still installs.
  local landed=""
  landed="$(sed -n 's/^[[:space:]]*"version":[[:space:]]*"\([^"]*\)".*/\1/p' "$dest/app/package.json" 2>/dev/null | head -1)"
  # KOSMOS_SRC is somebody explicitly choosing their bytes (a thumb drive,
  # a harness); the pointer has no authority over that choice, so the
  # assertion holds only for bytes the network delivered.
  if [ "$from_network" = yes ] && [ -n "${TARGET_VERSION:-}" ] && [ -n "$landed" ] && [ "$landed" != "$TARGET_VERSION" ]; then
    info "the release pointer says $TARGET_VERSION, but the files that landed are $landed."
    info "A cache between this computer and the download host served an old copy. Wait a minute, then paste the install line again."
    return 1
  fi
  info "on disk now: Kosmos ${landed:-(version unrecorded in this bundle)}"
  return 0
}

# ---- how it talks -----------------------------------------------------------
# ⚠️ Plain sentences, no jargon, no filenames the reader did not choose. The one
# screen a non-technical person cannot get past is the one written for somebody
# else.
step()  { printf '\n  %s\n' "$*"; }
info()  { printf '     %s\n' "$*"; }
ok()    { printf '     done\n'; }
die()   {
  printf '\n  Something went wrong.\n     %s\n\n' "$*" >&2
  [ -f "$LOG" ] && printf '  The details are in %s\n\n' "$LOG" >&2
  exit 1
}

# Everything also goes to a log, so one run produces a transcript rather than a
# memory of what happened. That is what makes the clean-machine test worth
# something afterwards.
#
# ⚠️ A FIFO AND tee, NOT `exec > >(tee ...)`. The page tells people to pipe
# this into `sh`, and macOS sh is bash in POSIX mode, where process
# substitution is a SYNTAX ERROR: the exact line the marketing page hands out
# died on line one of real use. Caught by running the script with sh, the way
# a user actually will, instead of with bash, the way its author did. The
# fifo spelling is plain POSIX and behaves identically; it is unlinked as
# soon as both ends are open, so nothing is left behind.
start_log() {
  mkdir -p "$LOG_DIR" || die "Could not create $KOSMOS_HOME. Check that your home folder is writable."
  # ⚠️ EVERY FILE LINE CARRIES THIS RUN'S ID (#237). The header lands in the
  # file synchronously while the body drains through a background reader, so
  # two overlapping runs interleave -- invisibly, because the text still reads
  # as ordered. Two readers independently misread one 4KB log from adjacency
  # alone, and this file is the one thing we ask a stranger to send us. The
  # console stays untagged (the person watching needs no run ids); only the
  # file, where runs can mix, says which line belongs to whom.
  printf '\n=== kosmos install %s · run %s ===\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$$" >> "$LOG"
  _pipe="$LOG_DIR/.log.pipe.$$"
  rm -f "$_pipe"
  if mkfifo "$_pipe" 2>/dev/null; then
    # awk, not tee: one reader, two shapes. `print` goes to the console
    # verbatim; the file copy is prefixed with the run id. fflush both ways,
    # or the file trails the console by a buffer and a crash loses the tail.
    awk -v id="$$" -v logfile="$LOG" '{ print "[" id "] " $0 >> logfile; fflush(logfile); print; fflush() }' < "$_pipe" &
    exec > "$_pipe" 2>&1
    rm -f "$_pipe"
  fi
  # No fifo (exotic filesystem): the install still narrates on screen, it
  # just loses the file transcript. Never fail the install for the log.
  # ⚠️ NO fd IS SAVED HERE. An `exec 3>&1` looked tidy and was never read;
  # its only effect was to be inherited by every child, which is exactly the
  # descriptor leak that once held a curl | sh install open forever.
}

# ---- uninstall --------------------------------------------------------------
# (Uninstall narrates to the screen only: its file transcript would live in
# the very folder being deleted, and tee holding an unlinked file preserves
# nothing. The screen is the record here, deliberately.)
# ─── the data root, defined ONCE (#1511) ──────────────────────────────────────
#
# 🛑 THIS FILE HELD THE THIRD DEFINITION OF THE DATA ROOT, AND IT IS THE ONE THAT
# DELETES. `engine/store.js` has `dataRootFor(platform, home, env)` as the single
# source, #570 made it one function and #1443 made every consumer resolve through
# it, and this script could not reach any of that, so the literal
# `$HOME/Library/Application Support` was written out at each site that needed it.
#
# 🔑 WHAT THIS HELPER IS: the shell's answer to the SAME question `dataRootFor`
# answers, in one place instead of several, so a future uninstaller for another
# platform copies a named thing rather than a scattered literal. On macOS the two
# agree exactly for the default input, measured: both give
# `$HOME/Library/Application Support/AgentWorkforce`. On an override carrying
# `./` or `..` they agree on the DIRECTORY and not on the string (node normalises,
# the shell squeezes slashes only), which is why the one captured value, and not
# a second derivation, feeds every comparison below.
#
# ⚠️ IT PREFERS THE PRODUCT'S OWN ANSWER WHEN THE INSTALL CAN GIVE ONE, AND THAT
# IS OFTEN NOT POSSIBLE. An uninstall runs against whatever version is installed,
# and `dataRootFor` only exists from #570 onward. Measured on a real 0.2.36
# install on this machine: the runtime and `app/engine/store.js` are both present
# and `dataRootFor` is NOT exported, so the consult correctly falls through. For
# every install older than #570 the literal IS the path, not a safety net, and
# writing it any other way would be a claim this cannot support.
#
# 🛑 AND IT MUST BE CALLED BEFORE `rm -rf "$KOSMOS_HOME"`, which is why it is
# called EXACTLY ONCE, in `uninstall()` before anything is removed, into `_support`, and every
# consumer reads that one value: that `rm` deletes `runtime/bin/node`, and the
# supervisor and litter removals need the answer hundreds of lines afterwards.
# ⚠️ The first version of this captured it at each consumer instead, and the one
# after the `rm` was asking an interpreter it had just removed, so it silently
# got the literal while the `remote/` removal above it got the product's answer.
# Two answers in one run is the inverse of this helper's purpose. The test
# asserts the single call site and its position, because a second call is the
# natural thing to add and it re-opens exactly that.
_kosmos_data_root() {
  _kdr=""
  if [ -f "$KOSMOS_HOME/runtime/bin/node" ] && [ -x "$KOSMOS_HOME/runtime/bin/node" ] \
     && [ -f "$KOSMOS_HOME/app/engine/store.js" ]; then
    # ⚠️ BOUNDED. This runs whatever store.js is INSTALLED, and a require that never
    # returns would hang the uninstall silently at the capture, which this file
    # names as the worst outcome (a hang with no sentence). macOS has no `timeout`,
    # so a shell watchdog kills the consult after KOSMOS_DATA_ROOT_CONSULT_SECONDS
    # (default 10; the test sets it low; a non-numeric value falls back to 10) and a
    # killed consult falls through to the literal exactly like the exit-3 path. A
    # JS-side timer cannot do this: a synchronous hang blocks the loop that would
    # fire it.
    # 🛑 THE WATCHDOG POLLS AND EXITS BY ITSELF. The first version was `sleep N; kill`,
    # and it left a process behind on EVERY outcome: on success the `sleep` was
    # orphaned for the rest of N, and on a non-zero consult exit `wait` aborted this
    # subshell under set -e before the watchdog was killed, so it outlived the
    # uninstall and fired at a dead pid. A loop on `kill -0` ends the moment node does.
    _kdr_secs="${KOSMOS_DATA_ROOT_CONSULT_SECONDS:-10}"
    case "$_kdr_secs" in ''|*[!0-9]*) _kdr_secs=10 ;; esac
    _kdr="$(
      KOSMOS_STORE="$KOSMOS_HOME/app/engine/store.js" "$KOSMOS_HOME/runtime/bin/node" -e '
        const s = require(process.env.KOSMOS_STORE);
        if (typeof s.dataRootFor !== "function") process.exit(3);
        process.stdout.write(String(s.dataRootFor(process.platform, require("os").homedir(), process.env)));
      ' 2>/dev/null &
      _kdr_pid=$!
      ( _n=0; while kill -0 "$_kdr_pid" 2>/dev/null; do
          _n=$((_n+1)); [ "$_n" -gt "$_kdr_secs" ] && kill "$_kdr_pid" 2>/dev/null; sleep 1; done ) >/dev/null 2>&1 &
      _kdr_rc=0; wait "$_kdr_pid" 2>/dev/null || _kdr_rc=$?
      exit "$_kdr_rc"
    )" || _kdr=""
  fi
  case "$_kdr" in
    /*) ;;
    *)
      # The fallback, normalised the way the guard below normalises its own
      # operands (`//` squeezed, trailing `/` dropped), so the two derivations
      # agree on the string and not only on the directory. ⚠️ A consult answer that
      # is NOT absolute lands here too, on purpose: it is what an old or odd store.js
      # returns, and the literal is the right answer for that install. An ABSOLUTE
      # answer without the leaf is refused below instead, because that is a store.js
      # answering with a different contract, and guessing past it steers a delete.
      # #2439: the store leaf is 'Kosmos' now (engine/store.js APP), migrated from the
      # legacy 'AgentWorkforce' leaf by maybeMigrateLegacyStore() on the board's first
      # access. This fallback runs ONLY when store.js could not be consulted (no installed
      # runtime), so the migration may not have run -- match this file's own write-side
      # pattern (~line 3522): the legacy leaf only when it exists and the new one does not,
      # else the new leaf. A fresh or sandboxed home (neither leaf present) resolves to
      # /Kosmos, agreeing with what the consult path (dataRootFor's APP default) returns --
      # before this, the fallback hardcoded /AgentWorkforce and so failed to match the
      # current-named jobs a post-rename install writes, orphaning them on a partial uninstall.
      _kdr="$(printf '%s' "${AGENT_WORKFORCE_DATA:-$HOME/Library/Application Support}" | /usr/bin/tr -s '/')"
      _kdr="${_kdr%/}"
      if [ -d "$_kdr/AgentWorkforce" ] && [ ! -d "$_kdr/Kosmos" ]; then
        _kdr="$_kdr/AgentWorkforce"
      else
        _kdr="$_kdr/Kosmos"
      fi ;;
  esac
  # 🛑 THE REFUSALS ARE ON THE RESULT, AND THERE ARE FIVE. IF YOU ADD A SIXTH, CHANGE
  # THE WORD FIVE. Every one is a delete that a bad input would have steered, and
  # each was found by construction:
  #   1 not absolute    `AGENT_WORKFORCE_DATA=rel` deleted relative to the cwd
  #   2 no store leaf   every rm below is bounded by the store leaf (/AgentWorkforce
  #                    OR /Kosmos -- both accepted during the #2439 migration window);
  #                    a consult answer of "/" or "$HOME" would have made "$_support/bin"
  #                    mean /bin or ~/bin. The trust boundary moved from a literal
  #                    to whatever the installed store.js returns, so the leaf is
  #                    checked here rather than assumed. (`/AgentWorkforce` or `/Kosmos`
  #                    directly under the root has the leaf and no parent, and is refused
  #                    by the same rule.)
  #   3 the system Library   HOME="" (set -u does not catch empty), HOME=/ and
  #                    HOME=// all resolve to /Library/Application Support, which no
  #                    per-user install owns. Refused by RESULT, and compared by
  #                    DEVICE:INODE as well as by string: the folder the answer
  #                    resolves to (through a symlink at the parent OR at the leaf,
  #                    and through a case variant on a case-insensitive filesystem)
  #                    must not have the system folder as its parent.
  #   4 a . or .. component   `/.`, `/x/..` and friends are the same folders by
  #                    other spellings, and every string comparison here is blind
  #                    to them. Refused outright rather than resolved.
  #   5 a shell-significant character   the value is spliced into a `grep -F`
  #                    pattern that gates `launchctl bootout` and `rm -f` on every
  #                    agent job, and grep -F treats a NEWLINE in the pattern as a
  #                    pattern SEPARATOR (the same mechanism KOSMOS_HOME is refused
  #                    for at the top of this file). Quote, backtick, dollar and
  #                    backslash are refused with it, the same posture.
  # Under this file's `set -e` a refusal aborts the uninstall at the capture,
  # before any rm, with the reason on stderr where a terminal shows it. Every
  # resolution below is guarded with `||` so an unenterable directory produces a
  # sentence, not a silent abort at an assignment.
  _kdr_nl="$(printf '\n_')"; _kdr_nl="${_kdr_nl%_}"
  _kdr_canon="$_kdr"
  if [ -d "${_kdr%/*}" ]; then
    _kdr_canon="$(cd "${_kdr%/*}" 2>/dev/null && pwd -P)/${_kdr##*/}" || _kdr_canon="$_kdr"
  fi
  # The folder the answer actually names, following a leaf symlink if there is one,
  # and its parent's device:inode. Empty when nothing exists yet, which is fine: a
  # folder that does not exist has nothing under it to delete.
  _kdr_real=""; _kdr_parent_ino=""; _kdr_sys_ino=""
  if [ -d "$_kdr" ]; then _kdr_real="$(cd "$_kdr" 2>/dev/null && pwd -P)" || _kdr_real=""; fi
  if [ -n "$_kdr_real" ] && [ -d "${_kdr_real%/*}" ]; then
    _kdr_parent_ino="$(/usr/bin/stat -L -f '%d:%i' "${_kdr_real%/*}" 2>/dev/null)" || _kdr_parent_ino=""
  elif [ -d "${_kdr%/*}" ]; then
    _kdr_parent_ino="$(/usr/bin/stat -L -f '%d:%i' "${_kdr%/*}" 2>/dev/null)" || _kdr_parent_ino=""
  fi
  _kdr_sys_ino="$(/usr/bin/stat -L -f '%d:%i' "/Library/Application Support" 2>/dev/null)" || _kdr_sys_ino=""
  case "$_kdr" in
    *"$_kdr_nl"*|*\'*|*\"*|*\`*|*\$*|*\\*)
      _kdr_why="it carries a newline, quote, backtick, dollar or backslash, which the ownership checks below cannot be trusted with" ;;
    */./*|*/../*|*/.|*/..)
      _kdr_why="it carries a . or .. component, which is the same folder under a spelling none of the checks here can see" ;;
    *)
      if [ -n "$_kdr_sys_ino" ] && [ "$_kdr_parent_ino" = "$_kdr_sys_ino" ]; then
        _kdr_why="the folder it names sits in the system-wide Library, which no per-user install owns (an empty or / HOME, or a link there, resolves here)"
      else
        case "$_kdr_canon" in
          "/Library/Application Support/AgentWorkforce"|"/Library/Application Support/Kosmos")
            _kdr_why="that is the system-wide Library, which no per-user install owns (an empty or / HOME resolves here)" ;;
          /*/AgentWorkforce|/*/Kosmos) printf '%s' "$_kdr"; return 0 ;;
          /*) _kdr_why="it does not end in /AgentWorkforce or /Kosmos with a parent folder above it, the shape every removal below is bounded by" ;;
          *)  _kdr_why="it is not an absolute path" ;;
        esac
      fi ;;
  esac
  # The offending value is printed through %s, never spliced into the format.
  printf 'refusing to uninstall: the data folder resolved to "%s", and %s. Check HOME and AGENT_WORKFORCE_DATA.\n' "$_kdr" "$_kdr_why" >&2
  return 1
}


uninstall() {
  step "Removing Kosmos."
  # Shared by the icon removals below: unregister BEFORE deleting (a -u on
  # an already-deleted path is likely a no-op, leaving the stale Spotlight
  # record the call exists to clear) and re-register on a failed removal
  # so a named survivor is not one Spotlight denies. Sandboxed runs never
  # touch the machine-global database.
  _lsreg=/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister
  # ⚠️ KOSMOS_HOME_APP_DIR IS A SANDBOX SIGNAL TOO (#945): a walk built with
  # it alone (the migration-era variable, honoured for the app dir at the
  # top of this file) slipped past every gate keyed on the other two and
  # read, wrote and registered against the operator's real surfaces.
  # Measured 2026-08-26 00:36 on the build Mac.
  _lsreg_u() {
    [ -z "${KOSMOS_APP_DIR:-}${KOSMOS_SYS_APP_DIR:-}${KOSMOS_HOME_APP_DIR:-}" ] || return 0
    [ -f "$_lsreg" ] && [ -x "$_lsreg" ] && "$_lsreg" -u "$1" >/dev/null 2>&1 || true
  }
  _lsreg_f() {
    [ -z "${KOSMOS_APP_DIR:-}${KOSMOS_SYS_APP_DIR:-}${KOSMOS_HOME_APP_DIR:-}" ] || return 0
    [ -f "$_lsreg" ] && [ -x "$_lsreg" ] && "$_lsreg" -f "$1" >/dev/null 2>&1 || true
  }
  # The board first, while the command that knows how still exists: deleting
  # the folder under a running server leaves it serving ghosts.
  if [ -f "$KOSMOS_HOME/bin/kosmos" ] && [ -x "$KOSMOS_HOME/bin/kosmos" ]; then
    info "stopping the board"
    # #4466: --force on every board start/stop/restart in this installer. `kosmos` refuses an AGENT's
    # stop/restart of a board that answers, and an install or update run from an agent's pane is not
    # the agent restarting the board. An older kosmos ignores the extra word.
    "$KOSMOS_HOME/bin/kosmos" stop --force >/dev/null 2>&1 || true
    # A refused stop (a board this command did not start) is NAMED rather
    # than glossed: the files still come off, but an orphan process would
    # keep the port and answer errors from a deleted tree, so the user
    # hears about it and gets the way out.
    if curl -fsS -m 2 "http://127.0.0.1:$PORT/" >/dev/null 2>&1; then
      info "note: something is still answering on port $PORT that this uninstall could not stop."
      info "It was not started by the kosmos command. Quit it, or restart your Mac, to finish."
    fi
  fi
  # ⚠️ AND THE BOARD'S OWN LOGIN JOB, which is newer than the agents' and does
  # not match their glob. Left behind, it is a launchd entry that runs a
  # deleted `kosmos` at every login forever — an orphan with a new cause, and
  # invisible to a person who believes they uninstalled the product.
  # ⚠️ SAME DERIVATION AS THE INSTALL PATH (#883), NOT THE BARE LABEL, or an
  # uninstall of a non-default KOSMOS_HOME install would look for
  # `com.kosmos.board.plist`, never find the suffixed file the install path
  # actually wrote, and leave it registered forever -- precisely the orphan
  # this whole block exists to prevent, just for the label instead of the
  # file. `_kosmos_home_default` matches the install path's own definition
  # exactly (both compare against the real, unsandboxed default), including
  # the SAME slash-normalization $KOSMOS_HOME itself already went through a
  # few lines up: a raw, un-normalized $HOME/.local/share/kosmos would not
  # string-equal a normalized $KOSMOS_HOME on a $HOME carrying a trailing or
  # doubled slash, which this file's own header already measured once
  # ("a trailing slash on $HOME made every ownership and board proof in
  # this file use //-flavored paths") -- the exact bug class, just for this
  # new comparison instead of the ones that comment already fixed.
  _kosmos_home_default="$(printf '%s' "$HOME/.local/share/kosmos" | /usr/bin/tr -s '/')"
  _kosmos_home_default="${_kosmos_home_default%/}"
  # 🔑 SAME DERIVATION AS THE INSTALL PATH (#883), NOW FOR THE DATA ROOT TOO,
  # NOT JUST THE LABEL ABOVE (#924). The label duplication above already
  # protects the launchd plist; it does nothing for `_remote_state` and
  # `_support` below, which key on AGENT_WORKFORCE_DATA. A caller who ran
  # this uninstall with KOSMOS_HOME set (a sandboxed walk) but
  # AGENT_WORKFORCE_DATA unset fell through to
  # `$HOME/Library/Application Support` -- the REAL, unsandboxed data root
  # -- while KOSMOS_HOME itself stayed correctly scoped, so the run LOOKED
  # targeted and swept somebody else's shared supervisor and remembered-
  # answer files instead. Measured live (#924): Pete's act-three uninstall
  # did exactly this. Caller's explicit choice still always wins, same as
  # every other ${VAR:-default} in this file.
  if [ -z "${AGENT_WORKFORCE_DATA:-}" ] && [ "$KOSMOS_HOME" != "$_kosmos_home_default" ]; then
    export AGENT_WORKFORCE_DATA="$KOSMOS_HOME/data"
  fi
  # 🔒 THE BELT, NOT JUST THE BUCKLE. The derivation above is the fix; this
  # is defense in depth for the day it doesn't fire (a future reorder, an
  # env quirk, a caller setting AGENT_WORKFORCE_DATA to the real path by
  # hand while also sandboxing KOSMOS_HOME by mistake). Same proof the
  # launchd label above already demands of itself: a non-default KOSMOS_HOME
  # must never resolve to the DEFAULT Application Support. If it somehow
  # does, refuse to touch it rather than silently sweep a different
  # install's shared data.
  # 🛑 THIS PAIR IS DELIBERATELY NOT ROUTED THROUGH `_kosmos_data_root` (#1511),
  # and it is not an oversight to tidy later. Two reasons, both load-bearing:
  #
  # 1. This guard COMPARES the two strings, so its correctness depends on both
  #    being produced the same way. Route one through a different derivation and
  #    the comparison can stop matching on formatting alone, which does not fail
  #    loudly: it SILENTLY DISABLES the refusal below, on a delete path.
  # 2. `_default_support` deliberately wants the REAL, unsandboxed default and
  #    must IGNORE AGENT_WORKFORCE_DATA, which is the opposite of what the helper
  #    is for.
  #
  # And these are BASE paths, without the `/AgentWorkforce` component that
  # `dataRootFor` returns. Feeding it here would need the last component stripped
  # back off, which is a FOURTH derivation rather than one fewer.
  _default_support="$(printf '%s' "$HOME/Library/Application Support" | /usr/bin/tr -s '/')"
  _default_support="${_default_support%/}"
  _resolved_support="$(printf '%s' "${AGENT_WORKFORCE_DATA:-$HOME/Library/Application Support}" | /usr/bin/tr -s '/')"
  _resolved_support="${_resolved_support%/}"
  if [ "$KOSMOS_HOME" != "$_kosmos_home_default" ] && [ "$_resolved_support" = "$_default_support" ]; then
    die "refusing to touch $_default_support: this uninstall is for a sandboxed install ($KOSMOS_HOME), and the real Application Support folder is not part of it. If you meant to remove the real install, run --uninstall with KOSMOS_HOME unset. If you meant to remove the sandboxed install, point AGENT_WORKFORCE_DATA at its own data root instead of the real one."
  fi
  # 🔑 THE DATA ROOT, RESOLVED ONCE, BEFORE ANYTHING IS DELETED (#1511). Every
  # consumer below (the Plus key, the shared supervisor, the remembered answers,
  # the litter sweep, the closing sentence) reads this variable and none calls
  # the helper again: after `rm -rf "$KOSMOS_HOME"` the interpreter it consults
  # is gone and a fresh call would quietly return the literal instead.
  _support="$(_kosmos_data_root)"
  _board_label=com.kosmos.board
  if [ "$KOSMOS_HOME" != "$_kosmos_home_default" ]; then
    _board_label="com.kosmos.board.$(printf '%s' "$KOSMOS_HOME" | shasum -a 256 | cut -c1-8)"
  fi
  _board_plist="${AGENT_WORKFORCE_LAUNCH:-$HOME/Library/LaunchAgents}/$_board_label.plist"
  if [ -f "$_board_plist" ]; then
    info "removing the login job for the board"
    # enable before bootout, for the same reason the agents' loop below does
    # it: a standing per-user `disable` override outlives the plist and would
    # silently refuse to start a reinstalled Kosmos.
    if [ -z "${AGENT_WORKFORCE_LAUNCH:-}" ]; then
      /bin/launchctl enable "gui/$(/usr/bin/id -u)/$_board_label" 2>/dev/null || true
      /bin/launchctl bootout "gui/$(/usr/bin/id -u)/$_board_label" 2>/dev/null || true
    fi
    rm -f "$_board_plist"
  fi
  # #2955: remove the board WATCHDOG login job too, the same way and for the same
  # reason as the board job just above. Without this, --uninstall leaves a watchdog
  # LaunchAgent behind that wakes on its interval and keeps trying to `kosmos start`
  # a board whose files this uninstall just deleted -- the exact orphan --uninstall
  # exists to prevent. Done BEFORE the orphan sweep below so this install's own
  # watchdog plist is already gone and cannot be double-handled by the glob.
  _wd_label=com.kosmos.board.watchdog
  if [ "$KOSMOS_HOME" != "$_kosmos_home_default" ]; then
    _wd_label="com.kosmos.board.watchdog.$(printf '%s' "$KOSMOS_HOME" | shasum -a 256 | cut -c1-8)"
  fi
  _wd_plist="${AGENT_WORKFORCE_LAUNCH:-$HOME/Library/LaunchAgents}/$_wd_label.plist"
  if [ -f "$_wd_plist" ]; then
    info "removing the board watchdog login job"
    if [ -z "${AGENT_WORKFORCE_LAUNCH:-}" ]; then
      /bin/launchctl enable "gui/$(/usr/bin/id -u)/$_wd_label" 2>/dev/null || true
      /bin/launchctl bootout "gui/$(/usr/bin/id -u)/$_wd_label" 2>/dev/null || true
    fi
    rm -f "$_wd_plist"
  fi
  # ⚠️ #918: EVERY DISTINCT KOSMOS_HOME GETS ITS OWN PERMANENT LABEL, per
  # #883's own fix above (a hash suffix whenever KOSMOS_HOME is non-default),
  # and nothing ever swept one whose KOSMOS_HOME later vanished -- a walk
  # convention that deletes its scratch directory directly, rather than
  # running --uninstall against that exact KOSMOS_HOME, leaves the label
  # registered forever, invisible to anyone who believes the scratch
  # install is gone. This uninstall is already touching launchd for its OWN
  # label (just above); sweep every OTHER board label at the same time.
  # By this point THIS install's own plist is already removed (the block
  # above), so it can never appear in the glob below and be double-handled.
  _sweep_dir="${AGENT_WORKFORCE_LAUNCH:-$HOME/Library/LaunchAgents}"
  if [ -d "$_sweep_dir" ]; then
    _uid="$(/usr/bin/id -u)"
    for _orphan_plist in "$_sweep_dir"/com.kosmos.board.*.plist; do
      # Matches this file's own sibling convention: the agents-sweep loop
      # just below uses the same `[ -e ]` idiom for the same no-match guard.
      [ -e "$_orphan_plist" ] || continue
      # ⚠️ THE BARE DEFAULT LABEL NEVER MATCHES THIS GLOB. `com.kosmos.board.plist`
      # has no fourth dot-segment between "board." and the ".plist" suffix
      # (#883's suffix is only ever added for a non-default KOSMOS_HOME), so this
      # loop only ever considers a SUFFIXED label -- a genuine sweep candidate,
      # never the one real board every normal install has.
      _orphan_label="$(basename "$_orphan_plist" .plist)"
      # #2955: the BARE-DEFAULT watchdog label (com.kosmos.board.watchdog, no #883
      # hash) DOES match this glob, unlike the bare-default board label -- so the
      # one real watchdog every normal install has would otherwise be a sweep
      # candidate, protected only by the runtime liveness check below rather than by
      # the lexical exclusion the default board plist enjoys. Skip it explicitly to
      # restore that two-layer protection: it is either this install's own (already
      # removed above, before the sweep) or the live default install's (which must
      # never be swept from under it). A SUFFIXED walk watchdog still flows through
      # the liveness check like any other orphan.
      [ "$_orphan_label" = com.kosmos.board.watchdog ] && continue
      # KOSMOS_HOME survives in exactly one place in this plist: the second
      # ProgramArguments string (the install path's own heredoc, above, never
      # writes it into EnvironmentVariables). PlistBuddy is the standard,
      # already-installed macOS tool for a structured read -- a homegrown XML
      # parse of a plist whose exact shape could drift is exactly the kind of
      # fragile code this file avoids everywhere else.
      # ⚠️ `|| _orphan_home_bin=""`, NOT A BARE ASSIGNMENT -- this file runs
      # under `set -euo pipefail`. PlistBuddy exits non-zero (not just an
      # empty string) whenever a plist genuinely fails to read: no
      # `ProgramArguments` key, a truncated file, or anything not valid XML
      # -- all explicitly anticipated by this very block's own "a future
      # format, a hand-edit" comment two lines below. Without the fallback,
      # a failing command substitution in a plain assignment is NOT exempt
      # from `set -e` (verified directly: the same shape aborts the whole
      # script mid-function, silently, the instant it runs) -- so ANY
      # unrelated malformed `com.kosmos.board.*.plist` sitting in a real
      # person's LaunchAgents would crash their entirely normal, healthy
      # uninstall partway through, before the agents' jobs, `bin/kosmos`
      # link, PATH line, and KOSMOS_HOME itself are ever removed. Caught in
      # challenge-loop iteration 3: rounds 1-2 hardened what happens when
      # PlistBuddy SUCCEEDS but returns something unexpected; nobody had
      # yet tested what happens when it fails to read at all. The `|| ""`
      # lets that failure land in the SAME `*) continue` arm a shape
      # mismatch already falls into -- "leave it alone rather than guess"
      # becomes true for a read failure too, not just a wrong shape.
      _orphan_home_bin="$(/usr/libexec/PlistBuddy -c 'Print :ProgramArguments:1' "$_orphan_plist" 2>/dev/null)" || _orphan_home_bin=""
      case "$_orphan_home_bin" in
        # ⚠️ `*` MATCHES ZERO-WIDTH: a ProgramArguments[1] of exactly
        # "/bin/kosmos" (no home prefix at all) still matches `*/bin/kosmos`
        # and would strip to an EMPTY `_orphan_home`. That empty string then
        # defeats both signals below: `[ -d "" ]` reads false ("gone"), and
        # `dirname ""` is POSIX-defined as "." -- a directory that always
        # exists -- so the parent-readability guard passes unconditionally
        # too. Caught in challenge-loop iteration 2: a degenerate plist
        # (hand-edited, or corrupted) would sail through both checks that
        # exist specifically to refuse an uncertain read. Required absolute
        # up front instead: a real KOSMOS_HOME this file ever derives is
        # always an absolute path, so anything else is already "not shaped
        # like this file's own writer produced" and refused the same way
        # the shape-mismatch arm below already refuses one.
        /*/bin/kosmos) _orphan_home="${_orphan_home_bin%/bin/kosmos}" ;;
        # #2955: the same glob (com.kosmos.board.*.plist) also catches a deleted
        # walk's WATCHDOG plist, whose ProgramArguments[1] is the watchdog script
        # rather than the kosmos bin. Derive its home the same way (strip the
        # script's own suffix) so a vanished walk's watchdog is swept too, rather
        # than left as the same #918 orphan this loop exists to prevent.
        /*/app/bin/board-watchdog.sh) _orphan_home="${_orphan_home_bin%/app/bin/board-watchdog.sh}" ;;
        # Not shaped like this file's own writer produced (a hand-edited or
        # future-format plist) -- leave it alone rather than guess.
        *) continue ;;
      esac
      # THE SIGNAL: does that KOSMOS_HOME still exist. A live walk in
      # progress (its directory present, its board plist just not yet touched
      # by ITS OWN --uninstall) must never be booted out from under it -- this
      # sweep only ever removes a label whose home is confirmed gone.
      [ -d "$_orphan_home" ] && continue
      # ⚠️ "GONE" MEANS CONFIRMED GONE, NOT "WE COULD NOT SEE IT JUST NOW".
      # A bare `[ -d ]` alone cannot tell a genuinely-deleted home apart from
      # one that is merely transiently unreachable (an unmounted volume, a
      # network share hiccup, an ancestor directory the process briefly
      # cannot stat) -- and this sweep runs on EVERY uninstall, unscoped to
      # the one KOSMOS_HOME the caller actually named, so an unrelated
      # uninstall hitting that window would boot out a still-wanted install's
      # job on a false read. If the PARENT directory is also unreadable right
      # now, that is exactly the shape of a transient outage rather than a
      # confirmed deletion (KOSMOS_HOME's own parent does not vanish on its
      # own) -- treat it as "cannot tell" and leave the label alone, matching
      # this whole feature's own rule that an honest "we could not check"
      # must never be acted on as a confirmed negative.
      [ -d "$(dirname "$_orphan_home")" ] || continue
      info "removing an orphaned background job for a deleted install ($_orphan_home)"
      # Same "no launchctl under a sandbox" rule as this install's own label
      # above: AGENT_WORKFORCE_LAUNCH set means a harness pointed the plist
      # directory at a temp folder, and there is no real registration there
      # to enable/bootout -- only the file itself is sandboxed and safe to
      # remove under a harness.
      if [ -z "${AGENT_WORKFORCE_LAUNCH:-}" ]; then
        /bin/launchctl enable "gui/$_uid/$_orphan_label" 2>/dev/null || true
        /bin/launchctl bootout "gui/$_uid/$_orphan_label" 2>/dev/null || true
      fi
      rm -f "$_orphan_plist"
    done
  fi
  _agents_stopped=no
  # ⚠️ THE SYMLINK GOES BEFORE THE FOLDER, AND `-L` IS CHECKED. `-e` follows
  # symlinks, so once the folder was deleted the dangling link answered
  # "nothing there" and survived every uninstall -- the user was told Kosmos
  # was removed while a dead `kosmos` stayed on their PATH. Measured.
  if [ -e "$BIN_DIR/kosmos" ] || [ -L "$BIN_DIR/kosmos" ]; then
    info "removing $BIN_DIR/kosmos"
    rm -f "$BIN_DIR/kosmos"
  fi
  # The PATH lines the installer wrote come out with the command they
  # served: exactly the marker and its export, by whole-line match, and
  # nothing else in the person's profile. awk (not grep -v) because an
  # empty result is a legitimate outcome (a profile that held only our
  # block), not a pipeline error to branch on.
  _profile="${KOSMOS_PROFILE_FILE:-$HOME/.zprofile}"
  case "$_profile" in
    /*) ;;
    *) _profile="" ;;
  esac
  # Same sandbox gate as the install side: a harness run touches only a
  # profile it names explicitly, never the operator's real one.
  if [ -n "${KOSMOS_APP_DIR:-}${KOSMOS_SYS_APP_DIR:-}${KOSMOS_HOME_APP_DIR:-}" ] && [ -z "${KOSMOS_PROFILE_FILE:-}" ]; then
    _profile=""
  fi
  _marker="$PATH_MARKER"
  _pline="$PATH_LINE"
  if [ -n "$_profile" ] && [ -f "$_profile" ] && grep -qxF "$_marker" "$_profile" 2>/dev/null; then
    _ptmp="$(mktemp "${TMPDIR:-/tmp}/kosmos-profile.XXXXXXXXXX" 2>/dev/null || true)"
    # The export is matched by ADJACENCY to the marker as well as by exact
    # text: an uninstall run with a different KOSMOS_BIN_DIR than the
    # install would otherwise remove the marker and orphan the export it
    # explained. Only an export-PATH-shaped line right after the marker
    # qualifies; anything else the person wrote there is printed untouched.
    # The single blank line the install printed before the marker is
    # swallowed with it (held one line, flushed unless the marker follows),
    # so install/uninstall cycles do not accumulate blank lines.
    # ⚠️ `cat > profile` TRUNCATES before it writes, so a failure mid-write
    # (disk full, permissions changed under us) would leave the person's
    # shell profile half-gone. A sibling backup is taken first and restored
    # on any failure; restore uses cat too, preserving a symlinked
    # profile's inode. mv is deliberately not used for the same reason.
    _pbak="$_profile.kosmos-uninstall-backup"
    # ⚠️ The backup is VERIFIED (cmp) before anything mutates the profile,
    # and it is only ever a restore SOURCE when verified: a cp that died
    # partway (disk full is this block's own named threat, and the backup
    # is the first write) would otherwise "restore" a partial copy over
    # the still-intact profile -- a shrinking write that succeeds on a
    # full disk -- and then claim nothing changed.
    # ⚠️ A pre-existing backup HALTS this block. It is a previous failed
    # run's preserved copy, which the person was told about by name;
    # overwriting it with the current (possibly damaged) profile, or
    # rm'ing it on this run's own failure path, would destroy exactly
    # what that run preserved. A run may only remove a backup it created.
    if [ -e "$_pbak" ]; then
      info "note: ${_pbak##*/} already exists from an earlier run; leaving it and the kosmos PATH line alone (the line is harmless and safe to delete by hand)"
      rm -f "$_ptmp" 2>/dev/null || true
      _bak_ok=halt
    else
    _bak_ok=no
    if [ -n "$_ptmp" ] && cp "$_profile" "$_pbak" 2>/dev/null && cmp -s "$_profile" "$_pbak" 2>/dev/null; then
      _bak_ok=yes
    fi
    fi
    # Announced unless HALTED (a halted run must not say "removing" and
    # then retract it). A failed-backup run still announces the attempt
    # and then reports the failure, which is the honest transcript.
    if [ "$_bak_ok" != halt ]; then
      info "removing the kosmos PATH line from ${_profile##*/}"
    fi
    if [ "$_bak_ok" = halt ]; then
      : # said above; nothing touched, and nothing was announced
    elif [ "$_bak_ok" = yes ] \
       && awk -v m="$_marker" -v p="$_pline" '
            skip { skip=0; if ($0 == p || $0 ~ /^export PATH=".*:\$PATH"$/) next }
            $0 == m { skip=1; blank=0; next }
            { if (blank) print ""; blank=0 }
            $0 == "" { blank=1; next }
            { print }
            END { if (blank) print "" }
          ' "$_profile" > "$_ptmp" 2>/dev/null \
       && cat "$_ptmp" > "$_profile" 2>/dev/null; then
      rm -f "$_ptmp" "$_pbak" 2>/dev/null || true
    elif [ "$_bak_ok" = yes ]; then
      # Something after the verified backup failed; put the original back,
      # and verify the restore too. A failed restore keeps the backup and
      # NAMES it -- a backup is never deleted on a failure path unless the
      # restore it fed verified byte-for-byte.
      if cat "$_pbak" > "$_profile" 2>/dev/null && cmp -s "$_pbak" "$_profile" 2>/dev/null; then
        rm -f "$_pbak" 2>/dev/null || true
        info "note: could not edit ${_profile##*/} (restored unchanged); the kosmos PATH line is harmless and safe to delete by hand"
      else
        info "note: could not edit ${_profile##*/}; an untouched copy is at ${_pbak##*/} in the same folder"
      fi
      rm -f "$_ptmp" 2>/dev/null || true
    else
      # The backup never verified, so the profile was never touched; the
      # partial backup is our own junk and comes off.
      rm -f "$_pbak" "$_ptmp" 2>/dev/null || true
      info "note: could not edit ${_profile##*/}; the leftover kosmos PATH line is harmless and safe to delete by hand"
    fi
  fi
  # ⚠️ THE AGENTS' BACKGROUND JOBS ARE STOPPED AND REMOVED. The app installs
  # one launchd job per agent (com.kosmos.agent.*), set to start at every
  # login. With Kosmos gone there is no UI left to manage them, and "left
  # alone" would mean invisible processes restarting forever with a manual
  # launchctl recipe as the only exit. The jobs are app plumbing; the
  # agents' FILES are user work and stay.
  _agents_dir="${AGENT_WORKFORCE_LAUNCH:-$HOME/Library/LaunchAgents}"
  # 🛑 EVERY FILE PROVES IT IS OURS BEFORE ANYTHING IS DONE TO IT (#931).
  # The glob above finds every Kosmos agent job in the directory, and the
  # directory is the REAL ~/Library/LaunchAgents whenever the caller
  # sandboxed KOSMOS_HOME without also pinning AGENT_WORKFORCE_LAUNCH
  # (Pete's release-walk convention, the same shape as #924). Before this,
  # a sandboxed --uninstall then booted out and deleted every real agent's
  # job on the machine. The board's own plist was already protected by its
  # KOSMOS_HOME-derived label (#883); the agents' labels are bare names, so
  # the proof has to come from INSIDE the file: engine/create.js's plistFor
  # writes this install's supervisor path into ProgramArguments, and that
  # path lives under the data root this uninstall resolved above
  # (`_support`, the ONE resolution captured before anything is removed; this
  # used to re-derive it from #924's base path, a second derivation that could
  # disagree with the product on the string for the same directory, so the
  # grep below missed and the job was left registered). A job that names a
  # different supervisor belongs to a different install and is left alone,
  # by name, rather than silently.
  _supervisor_ours="$_support/bin/agent-supervisor.sh"
  for _plist in "$_agents_dir"/com.kosmos.agent.*.plist; do
    [ -e "$_plist" ] || continue
    _label="$(basename "$_plist" .plist)"
    _name="${_label#com.kosmos.agent.}"
    if ! /usr/bin/grep -qF "<string>$_supervisor_ours</string>" "$_plist" 2>/dev/null; then
      info "leaving the background job for $_name: it belongs to a different Kosmos install ($_plist names another supervisor)"
      continue
    fi
    _agents_stopped=yes
    info "removing the background job for $_name"
    # ⚠️ enable BEFORE bootout, the order the app's own runbook uses. The
    # app's Remove path runs `launchctl disable`, which writes a per-user
    # override keyed on the LABEL that outlives the plist. Booting out and
    # deleting the plist while that override stands leaves a machine where
    # a reinstalled Kosmos creates an agent with the same name and launchd
    # silently refuses to start it, with nothing on disk to explain why.
    # ⚠️ AND ONLY OUTSIDE A SANDBOX (same escape as the board's block below):
    # the label came from a sandbox plist, but "gui/$uid" is the real domain,
    # so a sandboxed uninstall would boot out any REAL agent sharing a name.
    # The file removal after this is the sandboxed half and stays.
    if [ -z "${AGENT_WORKFORCE_LAUNCH:-}" ]; then
      /bin/launchctl enable "gui/$(/usr/bin/id -u)/$_label" 2>/dev/null || true
      /bin/launchctl bootout "gui/$(/usr/bin/id -u)/$_label" 2>/dev/null || true
    fi
    # The agent itself runs in a detached tmux session that outlives its
    # launchd job; with Kosmos gone it would keep running against a tmux
    # binary deleted out from under it. Killed BY NAME, one session per
    # plist found, never kill-server: on a machine with other tmux use,
    # the server is not ours to kill.
    # ⚠️ `=$_name`, NEVER the bare name: tmux target resolution falls back
    # to a PREFIX match, and this repo has already measured `kill-session
    # -t sam` killing samantha-discord (bin/agent-supervisor.sh records the
    # incident). The = forces an exact match, the same form every engine
    # call site uses.
    # ...and only after PROVING OWNERSHIP the way the supervisor does: the
    # session must carry @kosmos_agent naming itself, or a user's own
    # `tmux new -s notes` would die for sharing a name with an agent's
    # leftover plist.
    if [ -f "$KOSMOS_HOME/tmux/bin/tmux" ] && [ -x "$KOSMOS_HOME/tmux/bin/tmux" ]; then
      _owner="$("$KOSMOS_HOME/tmux/bin/tmux" show-options -t "=$_name" -v @kosmos_agent 2>/dev/null)" || _owner=""
      if [ "$_owner" = "$_name" ]; then
        "$KOSMOS_HOME/tmux/bin/tmux" kill-session -t "=$_name" 2>/dev/null || true
      fi
    fi
    rm -f "$_plist"
  done
  # 🛑 THE SWEEP THE PLIST LOOP CANNOT DO (#156). The loop above finds one
  # session per plist -- and anything that removed plists first (an earlier
  # wipe, a hand cleanup) leaves agents running with nothing left that can
  # find them. Rick: created by Kosmos, wiped, still running, back on every
  # board for a week. The sessions themselves carry the complete inventory:
  # @kosmos_agent naming the session is exactly the ownership proof the loop
  # already trusts, and it survives every file on disk being deleted. So the
  # uninstall also asks tmux directly, and kills only sessions that name
  # THEMSELVES ours -- a user's `tmux new -s notes` carries no option and a
  # borrowed name fails the equality, the same two gates as above.
  if [ -f "$KOSMOS_HOME/tmux/bin/tmux" ] && [ -x "$KOSMOS_HOME/tmux/bin/tmux" ]; then
    # 🛑 THE PIPELINE IS GUARDED, and the guard is load-bearing on EVERY
    # clean Mac: with no agents ever created there is no tmux server, so
    # `list-sessions` exits non-zero -- and under this script's pipefail
    # that unguarded pipeline ABORTED the whole uninstall right here, after
    # the kosmos command was removed and before the app, the login job and
    # KOSMOS_HOME were: a half-removed install on precisely the machine
    # with nothing to sweep. Found by the clean-machine target (tools/
    # clean-machine.sh) on its first run against the served installer.
    # An unreadable server (a NEWER system tmux owns the socket) takes the
    # same path: nothing listable means nothing sweepable, and the rest of
    # the uninstall must still run.
    # Capture-then-loop, not a guarded pipeline: forgiving the WHOLE
    # pipeline would also silence a future unguarded command in the loop
    # body, truncating the sweep while the uninstall then deletes the
    # agents' tmux out from under them. Only list-sessions is forgiven,
    # and the heredoc keeps the loop in THIS shell, so _agents_stopped
    # actually reaches the closing message that reads it (the pipeline
    # form assigned it in a subshell and the message was wrong for every
    # machine whose only agents ran without background jobs).
    _slist="$("$KOSMOS_HOME/tmux/bin/tmux" list-sessions -F '#{session_name}' 2>/dev/null || true)"
    while IFS= read -r _sname; do
      [ -n "$_sname" ] || continue
      _owner="$("$KOSMOS_HOME/tmux/bin/tmux" show-options -t "=$_sname" -v @kosmos_agent 2>/dev/null)" || _owner=""
      if [ "$_owner" = "$_sname" ]; then
        _agents_stopped=yes
        info "stopping $_sname (a Kosmos agent still running with no background job)"
        "$KOSMOS_HOME/tmux/bin/tmux" kill-session -t "=$_sname" 2>/dev/null || true
      fi
    done <<KOSMOS_SWEEP_LIST
$_slist
KOSMOS_SWEEP_LIST
  fi
  if [ -d "$KOSMOS_HOME" ]; then
    # ⚠️ REFUSE TO DELETE A FOLDER THAT IS NOT A KOSMOS INSTALL. KOSMOS_HOME
    # is overridable by design, and the one catastrophic misuse is pointing
    # it at a real folder (KOSMOS_HOME=$HOME) on the uninstall path: every
    # other destructive path here is bounded by a fixed leaf name, and this
    # one must be bounded by evidence.
    # A bare VERSION file proves nothing about this installer (common
    # enough that KOSMOS_HOME=$HOME plus a ~/VERSION would have deleted
    # the home folder); the VERSION leg exists for PARTIAL installs, and
    # a partial install always has one of our trees beside it.
    if [ -f "$KOSMOS_HOME/bin/kosmos" ] && [ -x "$KOSMOS_HOME/bin/kosmos" ] \
       || { [ -f "$KOSMOS_HOME/VERSION" ] && { [ -d "$KOSMOS_HOME/app" ] || [ -d "$KOSMOS_HOME/tmux" ]; }; }; then
      info "deleting $KOSMOS_HOME"
      # 🔑 RETIRE THIS MAC AT THE COORDINATOR WHILE IT CAN STILL SPEAK (#793).
      # The Mac's key lives in the support folder's remote/ dir and the
      # connector in the app tree about to go; after either is gone only a
      # signed-in phone can retire it. Best-effort with a short timeout, and
      # the outcome is said either way: an uninstall that silently leaves an
      # address on the account is how a name stays held forever.
      _remote_state="$_support/remote"
      _tunnel="$KOSMOS_HOME/app/bin/kosmos-tunnel"
      if [ -f "$_remote_state/mac_key" ] && [ -f "$_tunnel" ] && [ -x "$_tunnel" ]; then
        info "telling the Plus service this computer is going away"
        if "$_tunnel" retire --state-dir "$_remote_state" --coordinator "${AGENT_WORKFORCE_TUNNEL_COORDINATOR:-https://login.kosmosplus.com}" >/dev/null 2>&1; then
          info "its Plus address is retired; the name is free again after a day"
        else
          info "note: the Plus service could not be told; its address may still show on your account page until you remove it there"
        fi
        info "removing this computer's Plus key (its agents and their files are left alone)"
        rm -rf "$_remote_state" 2>/dev/null || true
      fi
      rm -rf "$KOSMOS_HOME"
    else
      info "note: $KOSMOS_HOME does not look like a Kosmos install, so it was left alone."
    fi
  fi
  # The icon goes too, or uninstall leaves a dead app that opens nothing.
  # BOTH default locations are swept -- installs before 2026-08-13 wrote
  # ~/Applications, newer ones prefer /Applications -- each bounded by the
  # fixed leaf name. Under the VERBATIM override only the override dir is
  # touched: KOSMOS_APP_DIR set means a sandbox, and a sandboxed uninstall
  # reaching into the machine's REAL Applications folders would delete a
  # real install out from under the person running the test.
  # (KOSMOS_SYS_APP_DIR alone does NOT sandbox the home-folder sweep in
  # the else-branch below; a hand-driven --uninstall using it must
  # override HOME too, as the harness always does.)
  if [ -n "${KOSMOS_APP_DIR:-}" ]; then
    # The SAME ownership gate as every other destructive site: the header
    # promise ("anything the uninstall cannot PROVE this installer
    # created is left alone and named") is unconditional, and the
    # override path is not an exemption. -e OR -L like every sibling, so
    # a dangling link is named rather than silently surviving.
    if [ -e "$APP_DIR/Kosmos.app" ] || [ -L "$APP_DIR/Kosmos.app" ]; then
      if bundle_is_ours "$APP_DIR/Kosmos.app"; then
        info "removing the Kosmos app"
        _lsreg_u "$APP_DIR/Kosmos.app"
        rm -rf "$APP_DIR/Kosmos.app" 2>/dev/null || { _lsreg_f "$APP_DIR/Kosmos.app"; info "note: could not remove $APP_DIR/Kosmos.app; drag it to the Trash to finish."; }
      else
        info "note: the Kosmos.app in $APP_DIR could not be proven to belong to this install and was left alone."
      fi
    fi
    for _res in "$APP_DIR"/.Kosmos.app.stage.* "$APP_DIR"/.Kosmos.app.old.*; do
      { [ -e "$_res" ] || [ -L "$_res" ]; } || continue
      if bundle_is_ours "$_res"; then
        rm -rf "$_res" 2>/dev/null || info "note: could not remove the leftover hidden folder $_res; drag it to the Trash to finish."
      else
        # "could not be proven": a foreign account's aside fails the grep,
        # but so does OUR OWN aside after its best-effort cleanup gutted
        # the launcher out of it (measured in the deep-locked world), and
        # "not created by this install" would be false there. Claim only
        # the failed proof.
        info "note: the leftover hidden folder $_res could not be proven to belong to this install and was left alone."
      fi
    done
  else
    # A hand-driven --uninstall with only the test-only KOSMOS_SYS_APP_DIR
    # override still sweeps the REAL home Applications folder (HOME decides
    # that side), and a prior reviewer proved the mistake is easy to make;
    # the sweep is at least named so a mis-driven run is visible.
    if [ -n "${KOSMOS_SYS_APP_DIR:-}" ]; then
      info "note: the home-folder side of this sweep uses $HOME_APP_DIR (KOSMOS_SYS_APP_DIR does not sandbox it; override HOME too in a test)"
    fi
    _sys_swept=no
    # The SYSTEM folder is shared between accounts, so its icon is deleted
    # only after PROVING OWNERSHIP the same way the tmux session kill does:
    # the bundle's launcher must name THIS install's KOSMOS_HOME. Without
    # the predicate, one account's uninstall would delete another
    # account's working icon. The HOME folder needs no predicate -- it is
    # per-user by construction.
    # -e OR -L, the same shape as resolve_app_dir's aliasing check: a
    # dangling symlink named Kosmos.app is residue too, and -d alone
    # leaves it invisible forever on the path whose header promises the
    # machine is returned to before.
    # (Ownership cannot be proven through a dangling link, so the refusal
    # note prints; that is honest, and the note names the survivor.)
    if [ -e "$SYS_APP_DIR/Kosmos.app" ] || [ -L "$SYS_APP_DIR/Kosmos.app" ]; then
      # The same anchored token as resolve_app_dir: the closing `}"` keeps
      # two homes in a prefix relationship from cross-matching, because
      # this grep is the sole gate on an rm -rf in a shared folder.
      if bundle_is_ours "$SYS_APP_DIR/Kosmos.app"; then
        info "removing the Kosmos app from $SYS_APP_DIR"
        # A standard user cannot always delete from /Applications; an icon
        # that survives is NAMED, never silently skipped. The flag feeds
        # the home-folder link branch below: a link is our residue only
        # when THIS RUN removed the bundle it pointed at.
        _lsreg_u "$SYS_APP_DIR/Kosmos.app"
        if rm -rf "$SYS_APP_DIR/Kosmos.app" 2>/dev/null; then
          _sys_swept=yes
        else
          _lsreg_f "$SYS_APP_DIR/Kosmos.app"
          info "note: could not remove $SYS_APP_DIR/Kosmos.app; drag it to the Trash to finish."
        fi
      else
        # "could not be proven": the failed match observed exactly that
        # and nothing more -- it covers another account's Kosmos, a
        # third-party app carrying the name, and a user's link to our
        # own bundle (linkness fails the proof by design).
        info "note: the Kosmos app in $SYS_APP_DIR could not be proven to belong to this install and was left alone."
      fi
    fi
    # ⚠️ Skipped when the two folders are physically the same (~/Applications
    # symlinked to /Applications): the ownership-checked branch above
    # already decided that bundle's fate, and this delete would override
    # its refusal through the symlink. FAIL CLOSED, the same shape as the
    # install-side guard: an unresolvable folder is a reason to leave the
    # bundle alone and say so, never a license to delete through it.
    _home_apps_phys="$(cd "$HOME_APP_DIR" 2>/dev/null && pwd -P)" || _home_apps_phys=""
    _sys_apps_phys="$(cd "$SYS_APP_DIR" 2>/dev/null && pwd -P)" || _sys_apps_phys=""
    # -e OR -L, the same shape as the system-folder gate above: -d follows
    # symlinks, so a dangling link named Kosmos.app here would survive
    # every uninstall in silence, against the survivor-is-NAMED rule.
    #
    # A LINK ENTRY is decided by its target, not by the tests below (which
    # would follow it onto whatever it points at): a link at the system
    # bundle this uninstall just swept is our residue and goes; any other
    # link was not made by this installer and is left, named.
    if [ -L "$HOME_APP_DIR/Kosmos.app" ]; then
      _lnk_target="$(readlink "$HOME_APP_DIR/Kosmos.app" 2>/dev/null)" || _lnk_target=""
      # BOTH conditions: pointing at our slot is not enough, because the
      # bundle there may have been foreign and refused two lines up (or
      # absent entirely), and "pointed at the removed Kosmos app" must
      # never print on a run that removed nothing. Measured in review:
      # the target-only version deleted a user's link to a refused
      # bundle, under two adjacent contradictory sentences.
      if [ "$_lnk_target" = "$SYS_APP_DIR/Kosmos.app" ] && [ "$_sys_swept" = "yes" ]; then
        info "removing a link that pointed at the removed Kosmos app from $HOME_APP_DIR"
        rm -f "$HOME_APP_DIR/Kosmos.app" 2>/dev/null || info "note: could not remove $HOME_APP_DIR/Kosmos.app; drag it to the Trash to finish."
      else
        info "note: the Kosmos.app in the Applications folder inside your home folder is a link this install did not create; it was left alone."
      fi
    elif [ -e "$HOME_APP_DIR/Kosmos.app" ]; then
      if [ -n "$_home_apps_phys" ] && [ -n "$_sys_apps_phys" ] && [ "$_home_apps_phys" != "$_sys_apps_phys" ]; then
        # The same ownership token as the system folder: uninstalling
        # Kosmos must not delete somebody's unrelated app that happens to
        # carry the name, even in the per-user folder.
        if bundle_is_ours "$HOME_APP_DIR/Kosmos.app"; then
          info "removing the Kosmos app from $HOME_APP_DIR"
          _lsreg_u "$HOME_APP_DIR/Kosmos.app"
          rm -rf "$HOME_APP_DIR/Kosmos.app" 2>/dev/null || { _lsreg_f "$HOME_APP_DIR/Kosmos.app"; info "note: could not remove $HOME_APP_DIR/Kosmos.app; drag it to the Trash to finish."; }
        else
          info "note: the Kosmos.app in the Applications folder inside your home folder was not created by this install and was left alone."
        fi
      elif [ -z "$_home_apps_phys" ]; then
        # The fail-closed note names the folder that actually failed the
        # check; blaming the home folder when the system one was the
        # unresolvable side would claim something never observed. (This
        # leg is believed unreachable -- seeing the entry already needs
        # the search bit cd needs -- and is kept as defense; no driving
        # pass is possible.)
        info "note: could not check the Applications folder inside your home folder; the Kosmos icon there was left alone."
      elif [ -z "$_sys_apps_phys" ]; then
        info "note: could not check $SYS_APP_DIR, so the Kosmos icon in the Applications folder inside your home folder was left alone."
      fi
    fi
    # Probe and stage residue from any earlier run goes too; the loop
    # CHECKS ITS RESULT and names any survivor, because the served header
    # promises this sweep and a deep-locked leftover really can refuse an
    # rm (measured: the best-effort version left a hidden .old folder in
    # the system folder under a closing line saying the machine was back
    # to before). The -e||-L test per entry keeps an unmatched glob
    # harmless. (Same accepted race as the probe sweep: a second
    # account's in-flight install could lose its hidden stage to this
    # sweep; bounded, rare.)
    rm -rf "$SYS_APP_DIR"/.kosmos-write-probe.* 2>/dev/null || true
    # ⚠️ WITH THE SAME OWNERSHIP PROOF as the visible bundle: an aside can
    # be another ACCOUNT'S only surviving icon (the restore-failure note
    # sends them to it by name), and residue that carries no provable
    # launcher is left and named rather than deleted, per the header's
    # stated bound.
    for _res in "$SYS_APP_DIR"/.Kosmos.app.stage.* "$SYS_APP_DIR"/.Kosmos.app.old.* \
                "$HOME_APP_DIR"/.Kosmos.app.stage.* "$HOME_APP_DIR"/.Kosmos.app.old.*; do
      { [ -e "$_res" ] || [ -L "$_res" ]; } || continue
      if bundle_is_ours "$_res"; then
        rm -rf "$_res" 2>/dev/null || info "note: could not remove the leftover hidden folder $_res; drag it to the Trash to finish."
      else
        # "could not be proven": a foreign account's aside fails the grep,
        # but so does OUR OWN aside after its best-effort cleanup gutted
        # the launcher out of it (measured in the deep-locked world), and
        # "not created by this install" would be false there. Claim only
        # the failed proof.
        info "note: the leftover hidden folder $_res could not be proven to belong to this install and was left alone."
      fi
    done
  fi
  # The shared supervisor is app plumbing (the same argument as the launchd
  # jobs) and goes; the STORE next to it is the user's agent records and
  # stays, and the closing sentence names where. `_support` was resolved once at
  # the top of this function, before the app tree (and its interpreter) went.
  if [ -d "$_support/bin" ]; then
    info "removing the shared supervisor"
    rm -rf "$_support/bin"
  fi
  # 🔑 THE APP'S OWN REMEMBERED ANSWERS ARE PLUMBING TOO, THE SAME ARGUMENT AS
  # THE SUPERVISOR ABOVE (#891). FOUR tiny files live at the data folder's
  # root, each holding one "have we asked this yet" fact the app checked once
  # so it would not ask again: whether first run has been seen
  # (first-run.json), the last app version the person was shown a what's-new
  # for (seen-version.json), whether the "we found your existing agents"
  # card was dismissed for good (found-agents-dismissed.json,
  # engine/discover.js's DISMISS_FILE), and which individual folders somebody
  # answered "this isn't an agent" about (found-agents-declined.json,
  # discover.js's DECLINED_FILE, #1531).
  #
  # ⚠️ THE FOURTH ONE WAS ADDED WITHOUT BEING ADDED HERE, WHICH IS THE WHOLE
  # POINT OF WRITING THE COUNT INTO THIS COMMENT. `found-agents-declined.json`
  # shipped hours before this line did, so an uninstall did NOT reset declines:
  # a person who said "this isn't an agent", uninstalled to start over, and
  # reinstalled got a screen that still hid that folder and no way to know why.
  # That is the exact case an uninstall exists to prevent.
  #
  # 📌 SO IF YOU ADD A FIFTH, CHANGE THE WORD "FOUR". The number is here to make
  # a missing member visible to a reader who is not looking for one, and the
  # family this belongs to is enumerated in engine/discover.js too. None of them
  # is the
  # person's data -- unlike "Forget my data" (engine/forget.js), which
  # deliberately KEEPS first-run.json so clearing your data does not also
  # re-trigger onboarding, uninstall removes the whole app, so a reinstall
  # should start from the same blank slate a first install does. `rm -f`
  # (not `-rf`: these are files, and `-f` is silent when one was never
  # written, e.g. a person who never opened the what's-new page).
  rm -f "$_support/first-run.json" "$_support/seen-version.json" \
    "$_support/found-agents-dismissed.json" "$_support/found-agents-declined.json"
  # ⚠️ Deliberately NOT removed: the user's agents' folders, their instruction
  # files, and anything under ~/work. Uninstalling the app must never delete
  # somebody's work, and an installer that cleans up too enthusiastically is
  # worse than one that leaves a folder behind.
  # Claim only what was observed: the plists were REMOVED (we removed them);
  # "stopped" would assert an outcome the best-effort bootout never checked.
  # And on a machine with no agents, say nothing about agents at all.
  # 🛑 OUR OWN BOOKKEEPING GOES; THE PERSON'S DATA STAYS (#1547). The status
  # engine writes a would-ping log into the data folder during normal running
  # (#1494), and the uninstall left it there -- so somebody who removed Kosmos
  # found our ping-logs sitting in their AgentWorkforce folder. Leave no trace
  # applies to what WE generated, never to what they made.
  #
  # ⚠️ BY EXACT NAME, NOT A GLOB, and that is this file's own rule rather than
  # caution for its own sake: every other rm here proves ownership first, and a
  # pattern-swept data folder is precisely how an uninstaller deletes the thing
  # it promised to keep. `wouldping/` is written by us and only by us; anything
  # we cannot name that confidently is left alone and named, per the header.
  #
  # 🛑 `$_support`, NOT A SECOND DERIVATION. AGENT_WORKFORCE_DATA is the PARENT
  # of the AgentWorkforce folder, not the folder itself (`engine/store.js:85`
  # joins APP onto it), and a first version of this block re-derived the path and
  # dropped that segment -- so it looked in `$AGENT_WORKFORCE_DATA/wouldping`
  # while the log lives in `$AGENT_WORKFORCE_DATA/AgentWorkforce/wouldping` and
  # the sweep silently did nothing. It only appeared to work on a fully default
  # install, where the fallback happens to include the segment.
  # ⚠️ AND `uninstall()` ITSELF EXPORTS THAT VARIABLE at the top of this function
  # whenever KOSMOS_HOME is non-default, so every non-default install was missed.
  # This file's own header states the rule that would have prevented it: two
  # derivations of one string is how a sweep silently stops matching what the
  # install wrote. `_support` is computed once, above, and is in scope here.
  # 🛑 SIX DIRECTORIES, AND IF YOU ADD A SEVENTH CHANGE THE WORD "SIX". The number
  # is here to make a missing member visible to a reader who is not looking for one,
  # exactly as the remembered-answer block above does, and for the same reason: that
  # block records that its fourth member shipped hours before it was listed there.
  #
  # 🛑 DERIVED BY SEARCH, NOT BY RECALL, AND THAT DISTINCTION IS THE WHOLE HISTORY OF
  # THIS BLOCK. The first version swept ONE directory and the plan called it "the only
  # litter I could name confidently" -- a sentence about my memory that reads as a fact
  # about the codebase. A reviewer found a second. The sentence was then corrected and
  # THE METHOD WAS NOT, so a second reviewer found four more. The list below comes from
  # `grep -n "store\.ROOT"` across the engine, which is the command that should have
  # been run first:
  #
  #   REMOVED, ours: we write it, we are the only writer, and it is rebuilt on next run
  #     downloads    the provider binaries we downloaded. THE BIG ONE: connect.js
  #                  records a stranded copy costing ~281MB, so leaving this behind
  #                  while removing a JSONL ping log gets the priority exactly backwards
  #     usage        a derived cache, recomputed from transcripts
  #     sendertokens tokens WE mint (mode 0700); leaving agent credentials on disk
  #                  after an uninstall is a residue question, not only tidiness
  #     selfreports  agent state records we append
  #     wouldping    the ping log this card was filed about
  #     liveness     agent heartbeats
  #
  #   LEFT ALONE AND NAMED, per this plan's Scope rule. Not oversights:
  #     chats, commitments      the person's, by `engine/forget.js:45` -- the "Forget my
  #                             data" surface, whose own comment says adding a name
  #                             there is the only way to widen it
  #     projects.json, profiles, attachments, messages.jsonl, messages, avatars,
  #     you.json, you-avatar     the person's work and their own profile
  #     secrets                 THE PERSON'S CREDENTIALS. We wrote the files; the keys
  #                             inside are theirs, and destroying them on an uninstall
  #                             they may be reversing is not ours to decide
  #     connect.json, removed.json, room-seen.json
  #                             records of the PERSON'S DECISIONS. We write them, so
  #                             they are arguably ours, and that is exactly why they
  #                             are named rather than swept: "we wrote it" is not the
  #                             test, "it is ours rather than theirs" is
  #     created.jsonl, trust-writes.json, styles.json, ping.json, remote.json,
  #     remote-status.json, github-app.json, autoupdate.json, engmode.json,
  #     limits.json, notify.json, policy.json
  #                             OURS BY THE SAME RULE AS THE SWEPT LIST, AND
  #                             DELIBERATELY NOT SWEPT. See the note below.
  #
  # 🛑 ALREADY REMOVED ABOVE, SO DO NOT ADD THEM HERE: `first-run.json`,
  # `seen-version.json`, `found-agents-dismissed.json` and `found-agents-declined.json`
  # go at the `rm -f` of the four remembered-answer files ("the app's own remembered answers").
  # 🛑 `remote/` IS DIFFERENT AND THIS ROW USED TO CALL IT SIMPLY HANDLED. It is
  # removed at `rm -rf "$_remote_state"`, but only inside FOUR nested conditions: KOSMOS_HOME exists, the
  # ownership gate passes, `remote/mac_key` exists, AND the tunnel binary is executable.
  # On a partial install, a second --uninstall, a bundle without the tunnel, or any run
  # failing the ownership gate, `remote/` SURVIVES.
  # ⚠️ AND IT IS THE ONE LEFTOVER THAT IS A CREDENTIAL: it holds this Mac's Plus
  # key. The row that was wrong was the row holding an actual key, in a table whose
  # justification for sweeping `sendertokens` is that leaving credentials behind is a
  # residue question. Stated as a CONDITION rather than a fact, because a maintainer
  # reads this table as a map of the folder.
  # 📌 Distinct from the `remote.json` and `remote-status.json` FILES, which are
  # left alone above; unsaid, the two files' row reads as covering the directory.
  # 📌 `bin/` is removed at `rm -rf "$_support/bin"` ("removing the shared supervisor"), above.
  # put two contradictory rulings about the same four files in one function, and the
  # newer one was wrong. A maintainer reading this table to decide whether a fifth
  # decision-record is safe would have got the wrong answer.
  #
  # 🛑 WHY THE SWEEP STOPS AT SIX RATHER THAN TAKING THE TWELVE NAMED ABOVE AS OURS.
  # This is a deliberate call, not an omission. Each round of widening this list has
  # introduced a defect: adding `liveness` and `selfreports` silently falsified the
  # closing sentence of the whole uninstall, because both are keyed PER AGENT and that
  # sentence named their folder as untouched. The six swept are directories of pure
  # machine output with no per-person content. The eleven are single files, several
  # holding settings a person set (`engmode`, `limits`, `notify`, `policy`), and each
  # would need its own reading of ours-versus-theirs. Naming them is free and cannot
  # break anything. Deleting them cannot be undone. If a later card wants them, it
  # should take them one at a time with that reading written down.
  #
  # 📌 AND THE LIST ABOVE WAS NOT DERIVED BY `grep store.ROOT` ALONE, BECAUSE THAT
  # COMMAND IS BLIND: `engine/styles.js:20` and `engine/trust.js:393` write through an
  # inline `require('./store').ROOT`, and `engine/create.js:1683` goes through a
  # `supportDir()` helper. `grep -c 'store\.ROOT' engine/styles.js` returns ZERO for a
  # file that writes there. Search for the WRITES (`path.join(` with a root-ish first
  # argument) and read them, rather than for one spelling of the root.
  # ⚠️ REMOVE FIRST, THEN CLAIM, which is this function's stated rule three lines up:
  # "Claim only what was observed". Announcing before the attempt and swallowing the
  # failure with `|| true` (required here, the file is `set -euo pipefail`) told the
  # person records were removed when a permission error meant they were not. The
  # neighbouring leftover-folder code ("removing the shared supervisor") already does it this way.
  _swept=no
  _swept_left=""
  for _litter in downloads usage sendertokens selfreports wouldping liveness; do
    if [ -d "$_support/$_litter" ]; then
      rm -rf "$_support/$_litter" 2>/dev/null || true
      if [ -d "$_support/$_litter" ]; then _swept_left="$_swept_left $_litter"; else _swept=yes; fi
    fi
  done
  # 📌 ONE LINE, IN THE PERSON'S WORDS. An earlier version said "removing Kosmos's own
  # wouldping records", printing a MODULE NAME to somebody uninstalling an app, once
  # per directory, so six removals read as more happening than had. The neighbours are
  # the model: "removing the shared supervisor", "stopping the board".
  # 🛑 "LEFTOVER FILES", NOT "RECORDS ABOUT YOUR AGENTS". Three of the six are not
  # records about agents at all: `downloads` is provider binaries, `usage` is a cache
  # derived from the person's own transcripts, `sendertokens` are minted credentials.
  # The biggest thing this removes was being announced as something it is not.
  # ⚠️ AND IT MUST NOT MENTION AGENTS, because it fires on machines that have none:
  # `downloads/` is written by the provider-connect flow and `usage/` from the person's
  # own ~/.claude dirs, both before any agent exists. The rule is stated beside the four remembered-answer files
  # -- on a machine with no agents, say nothing about agents at all.
  if [ "$_swept" = yes ]; then
    # ⚠️ NOT AN UNQUALIFIED PAST TENSE, AND DELIBERATELY NOT GATED ON
    # `_swept_left` EITHER. The closing line below was fixed to require nothing left
    # behind; the same fix here gives the opposite defect, six directories removed
    # and the transcript saying nothing at all. The wording carries it instead.
    info "removed Kosmos's own leftover files (your projects, conversations and sign-ins stay; see any notes below)"
  fi
  # ⚠️ NAMES WHAT SURVIVED AND WHERE, which this file's header (setup.sh:89) requires of
  # every leave-behind: "on the rare machine where that leaves something behind, the
  # sentence says what it is". Every sibling note in this function names a path; this
  # was the only one that named nothing.
  if [ -n "$_swept_left" ]; then
    for _litter in $_swept_left; do
      info "note: could not remove $_support/$_litter; it is Kosmos's own and safe to delete"
    done
  fi
  if [ "$_agents_stopped" = "yes" ]; then
    # 🛑 THIS SENTENCE WAS TRUE UNTIL THE SWEEP ABOVE EXISTED, AND THE SWEEP IS WHAT
    # FALSIFIED IT. It named the AgentWorkforce folder as a place agents' files were
    # left alone; `liveness/` and `selfreports/` are keyed PER AGENT in that folder
    # (`liveness/angel.json`, `selfreports/angel.jsonl`) and the sweep removes them.
    # A closing line on an uninstall exists to say truthfully what survived, so it
    # names the split rather than the folder.
    # 🛑 THE SECOND CLAUSE IS CONDITIONAL AND MUST STAY THAT WAY. Written flat, it
    # asserted the leftover files were removed even when the sweep had just FAILED and
    # said so four lines above, and even when there was nothing to sweep and no line was
    # printed at all. A closing sentence that contradicts a note in its own transcript is
    # worse than no closing sentence.
    # ⚠️ BOTH CONDITIONS. `_swept` is yes when ANY directory went, so with five removed
    # and one stuck it was still making the unqualified claim while a note above named
    # the survivor. The unqualified sentence needs nothing left behind, not something
    # taken. Caught by the failure-path test rather than by reading.
    if [ "$_swept" = yes ] && [ -z "$_swept_left" ]; then
      printf '\n  Kosmos is removed. Your agents\047 background jobs were removed, and so were\n'
      printf '  Kosmos\047s own leftover files. Your agents\047 own folders, and your projects,\n'
      printf '  conversations and sign-ins, were left alone in\n'
      printf '  %s\n\n' "$_support"
    else
      printf '\n  Kosmos is removed. Your agents\047 background jobs were removed; your projects,\n'
      printf '  conversations and sign-ins were left alone in\n'
      printf '  %s\n\n' "$_support"
    fi
  else
    printf '\n  Kosmos is removed.\n\n'
  fi
  # ⚠️ Named, not removed: the install may have recorded the agent
  # permission setting in Claude Code's own config, but that file can carry
  # the person's real settings and the same key set by their own hand --
  # an uninstaller cannot tell, so deleting it would overstep. The
  # reversibility contract is honored by NAMING what was left, per the
  # header's rule that anything not removed is left alone and named.
  if [ -f "$HOME/.claude/settings.json" ] && grep -Eq '"skipDangerousModePermissionPrompt": *true' "$HOME/.claude/settings.json" 2>/dev/null; then
    # ⚠️ THE VALUE, NOT THE KEY (#932): the sibling gate below learned this
    # first (hasTrustDialogAccepted). A key present and false, set by the
    # person's own hand or flipped back after install, means nothing was
    # left in effect and the question is already back, and every clause of
    # the sentence below would be wrong.
    printf '  One setting was left in place: skipDangerousModePermissionPrompt in\n'
    printf '  ~/.claude/settings.json (agents skip per-action permission prompts).\n'
    printf '  Delete that line there if you want the question back.\n\n'
  fi
  # #3946: the status line Kosmos adds to record weekly usage is ours by its marker,
  # but the bundled Node that could edit the JSON is gone by now, so it is NAMED, as
  # the header's rule asks. Left in place it points at files this uninstall removed,
  # so it records nothing any more, and it keeps the one status-line slot.
  # Every account Kosmos wires, not only the default: account folders are kept by this
  # uninstall, so their entries would otherwise be left unnamed.
  # Two passes over the same glob rather than one space-joined list, so a path with a
  # space in it is printed whole.
  _sl_left=""
  for _sl in "$HOME/.claude/settings.json" "$HOME"/.claude-*/settings.json; do
    [ -f "$_sl" ] && grep -q 'kosmos-statusline\.js' "$_sl" 2>/dev/null && _sl_left=yes
  done
  if [ -n "$_sl_left" ]; then
    printf '  Kosmos\047s status line was left in these settings files (the "statusLine"\n'
    printf '  entry naming kosmos-statusline.js). It records nothing now; delete that entry\n'
    printf '  if you want to use a status line of your own:\n'
    for _sl in "$HOME/.claude/settings.json" "$HOME"/.claude-*/settings.json; do
      [ -f "$_sl" ] && grep -q 'kosmos-statusline\.js' "$_sl" 2>/dev/null && printf '    %s\n' "$_sl"
    done
    printf '\n'
  fi
  # ⚠️ AND THE SECOND THING WE LEFT IN THAT TOOL'S CONFIG, named for exactly the
  # same reason. Creating an agent records that Claude Code trusts the folder
  # Kosmos made for it, and an uninstaller cannot tell those lines from ones the
  # person accepted themselves at the same paths. Deleting them would overstep;
  # leaving them SILENTLY would break the header's rule that anything not
  # removed is left alone and NAMED — which is the rule this whole block exists
  # to honour, and which a new leftover quietly opts out of.
  #
  # ⚠️ `grep`, not a JSON read, and the sentence is written to what grep can
  # actually prove: the file MENTIONS the key. By this point the bundled Node is
  # gone, so there is nothing here that can parse the file, and a sentence that
  # counted entries would be a claim this code cannot support.
  # 🛑 THIS PARAGRAPH USED TO END "SO THE MARKS STILL APPLY", AND #1659 MADE
  # THAT FALSE FOR SOME OF THE LINES BELOW. Corrected here rather than left to
  # contradict the sentence 84 lines down that already says so.
  # It was true and useful when written: a LIVE account's folder is left alone, so
  # its mark is not stale and opening that folder later will not ask.
  # What changed: the sweep now also lists `.removed-claude-*`, and NOTHING points
  # CLAUDE_CONFIG_DIR at a forgotten account. That is the entire point of the
  # rename, and engine/status.js:198 skips the prefix deliberately. So for those
  # lines the mark does NOT still apply, opening one of those folders WILL ask, and
  # the `_trust_removed` sentence below is what tells the person which case is
  # theirs. Two flags and two sentences on purpose: one sentence covering both
  # would be false for whichever half the person actually has.
  # (Mona Lisa, 2026-08-21; she checked the folder
  # fact against the notice above rather than assuming the two shapes matched.)
  #
  # ⚠️ THE PARENTHETICAL IS LOAD-BEARING, per the precedent above: a key name
  # shouted at somebody who has just removed the only thing that could explain
  # it is not a disclosure. Name it, translate it, say the undo.
  # 🛑 THE GATE HAS TO SUPPORT THE SENTENCE, AND THE FIRST ONE DID NOT. It was
  # `grep -q 'hasTrustDialogAccepted'`, which matches on essentially ANY Claude
  # Code config: measured on this machine, 22 entries and NONE of them lack the
  # key. So it fired for people Kosmos had never written a byte for, and told
  # them their agents' folders were recorded as trusted.
  #
  # ⚠️ TWO NARROWINGS, both cheap, and the "nothing here can parse JSON" excuse
  # reached neither of them. First, the value: only a `true` is a trust mark at
  # all (19 of the 22 here are `false`, which is Claude Code's default rather
  # than an answer). Second, `_agents_stopped`: the paragraph above deliberately
  # says nothing about agents on a machine that had none, and this block was
  # contradicting it three lines later — and its own sentence "those folders are
  # still on your machine" is only true because THAT paragraph left them there.
  # 🛑 #1629: EVERY CONFIG AN AGENT COULD READ, NOT JUST THE DEFAULT ONE. Claude
  # Code reads trust from `$CLAUDE_CONFIG_DIR/.claude.json` when that variable is
  # set, and Kosmos points agents at per-account config dirs (`~/.claude-*`). This
  # checked `$HOME/.claude.json` alone, so on a machine whose agents ran under
  # other accounts it said nothing while the marks it describes were sitting in a
  # file one directory over -- a true-sounding silence.
  # ⚠️ It also NAMED that one file in its sentence, so even when it did fire the
  # remedy pointed at the wrong place. It now names the files it actually found.
  _trust_marked=''
  # 🛑 TWO FLAGS, NOT ONE, AND THE ONE-FLAG VERSION WAS MINE. A single
  # `_trust_removed` gated a pair of sentences that assert OPPOSITE things: "for a
  # folder you still use, the mark applies" claims a LIVE mark, and the next line
  # claims a REMOVED one. On a machine whose ONLY marked config belongs to a
  # disconnected account, the first sentence is false, and the header above it is
  # false of every file in the list. Reachable, not theoretical: this block's own
  # comment records 19 of 22 configs on the fleet machine carrying `false`.
  # Initialised here rather than relying on `${x:-no}`, so the two read like the
  # list they sit beside.
  _trust_live=no
  _trust_removed=no
  # 🛑 FORGOTTEN ACCOUNTS TOO (#1659). Removing an account RENAMES its directory
  # to `.removed-claude-<label>` and deliberately KEEPS the config inside, so the
  # trust mark survives in a file this sweep could not match. The person was then
  # told their trust marks were accounted for while one sat in plain sight, which
  # is the exact true-sounding silence the note above describes, arriving through
  # a directory name that did not exist when that fix was written.
  # 🛑 NO CODEX ENTRY, AND THAT IS DELIBERATE RATHER THAN AN OMISSION. An earlier
  # version of this line added `.removed-codex-*/.claude.json` "for symmetry".
  # IT IS A DEAD GLOB: codex homes store `auth.json` (openaiaccounts.js:58) and
  # codex agents launch with CODEX_HOME, never CLAUDE_CONFIG_DIR, so no
  # `.claude.json` can exist there. Adding it looked like completeness and was a
  # pattern that can never match -- the same decoration this sweep exists to
  # avoid. Note there is no live `.codex-*/.claude.json` in this loop either,
  # which is the tell: the asymmetry is real, not an oversight.
  for _cfg in "$HOME/.claude.json" ${CLAUDE_CONFIG_DIR:+"$CLAUDE_CONFIG_DIR/.claude.json"} "$HOME"/.claude-*/.claude.json "$HOME"/.removed-claude-*/.claude.json; do
    [ -f "$_cfg" ] || continue
    grep -q '"hasTrustDialogAccepted": true' "$_cfg" 2>/dev/null || continue
    case " $_trust_marked " in *" $_cfg "*) continue ;; esac
    _trust_marked="$_trust_marked $_cfg"
    # 🛑 ONLY SAY THE DISCONNECTED-ACCOUNT SENTENCE IF THERE IS ONE. Without this
    # flag those two lines printed on EVERY uninstall, so the overwhelmingly common
    # machine (one ~/.claude.json mark, no account ever disconnected) was told about
    # a state the person has never been in. That is the same "a reason that is true
    # only sometimes, stated as fact" defect this block's own comments were rewritten
    # twice to remove, arriving a third time from the side that looks like extra
    # helpfulness.
    case "$_cfg" in
      "$HOME"/.removed-claude-*) _trust_removed=yes ;;
      *) _trust_live=yes ;;
    esac
  done
  if [ "$_agents_stopped" = "yes" ] && [ -n "$_trust_marked" ]; then
    printf '  Trust marks were left in place. These files each carry a mark that\n'
    printf '  records a folder as trusted:\n'
    # ⚠️ UNQUOTED ON PURPOSE, and said so because it looks like the word-splitting
    # bug this fleet keeps finding: `$_trust_marked` is a space-joined LIST built
    # above, so it MUST split. What it cannot survive is a path containing a space,
    # and #1659 adds another source of paths into that accumulator, so the hazard is
    # now fed from two places rather than one. Pre-existing and not fixed here;
    # named so the next person meets it as known rather than as a discovery.
    for _cfg in $_trust_marked; do printf '    %s\n' "$_cfg"; done
    # 🛑 THE OLD SENTENCE SAID "the marks still apply" AND #1659 MADE THAT FALSE FOR
    # SOME OF THE LINES ABOVE. The sweep now also lists `.removed-claude-*`, and
    # nothing points CLAUDE_CONFIG_DIR at a forgotten account: that is the point of
    # the rename, and engine/status.js skips the prefix deliberately. So the mark in
    # a disconnected account's config is INERT, and telling someone it is in effect
    # is the same true-sounding-but-wrong disclosure this block was fixed for twice
    # before. Listing the leftover file is right; asserting it still bites is not.
    if [ "$_trust_live" = yes ]; then
      printf '  For a folder you still use, the mark applies, so Claude Code does not\n'
      printf '  ask before working in it.\n'
    fi
    if [ "$_trust_removed" = yes ]; then
      printf '  For an account you disconnected, the file is still there but nothing\n'
      printf '  reads it, so you will be asked again if you reconnect that account.\n'
    fi
    printf '  Remove these entries if you want the question back everywhere.\n\n'
  fi
  exit 0
}

# ⚠️ EVERYTHING SIDE-EFFECTFUL LIVES IN main, INVOKED ON THE LAST LINE.
# A `curl | sh` reader executes stdin incrementally, so a connection dropped
# mid-file would otherwise run the script's PREFIX and then die with a raw
# syntax error -- half an install performed by a truncated download. With
# the wrapper, a truncated file parses (or fails to parse) without ever
# having done anything: main only runs if the closing line arrived.
main() {

# ⚠️ AN UNRECOGNISED FLAG REFUSES, IT DOES NOT INSTALL. The one argument
# this script takes is the one that UNDOES the install; a typo in it
# (--uninstal, -uninstall, --help) silently doing the opposite would be
# indefensible. No argument at all is the install.
case "${1:-}" in
  "") ;;
  --uninstall) uninstall ;;
  *)
    printf '\n  The only option is --uninstall. To install, run it with no options:\n' >&2
    printf '    curl -fsSL https://installkosmos.com/setup | sh\n\n' >&2
    exit 2
    ;;
esac

# ---- preflight --------------------------------------------------------------
# ⚠️ ASK WHETHER THIS IS A FRESH MACHINE **BEFORE** ANYTHING CREATES A DIRECTORY.
# The first version asked afterwards, and `start_log` had already made
# $KOSMOS_HOME/logs to write into. So the installer created the evidence it then
# used to decide, and told a person installing for the very first time
# "Kosmos is already installed here."
#
# Caught by running it against a genuinely empty directory. On the never-touched
# Mac that is the FIRST SENTENCE the user would have read, and it says the
# product is confused about its own state on the one run where trust is decided.
# ⚠️ Keyed on the INSTALLED PRODUCT, not on the directory existing: start_log
# creates $KOSMOS_HOME/logs before anything can fail, so a run that died at a
# dropped download left the directory behind, and the RETRY -- the likeliest
# second run there is -- opened with "already installed here" on a machine
# where Kosmos has never run. The launcher existing is what installed means.
FRESH_INSTALL=yes
[ -f "$KOSMOS_HOME/bin/kosmos" ] && [ -x "$KOSMOS_HOME/bin/kosmos" ] && FRESH_INSTALL=no

start_log

printf '\n  Installing Kosmos\n'
printf '  This takes a couple of minutes and does not need your password.\n'

# The version this run SET OUT to install, resolved before any artifact
# moves, so the log can answer which release a run was and the read-back
# after the swap has something to hold the landed files against. The
# pointer is tiny and fetched with a cache-busting query: a stale edge
# handing out an old pointer would quietly aim the whole run at the past.
# An unreachable pointer degrades to a versionless run that says so.
TARGET_VERSION=""
# #2036: which channel pointer to read. DEFAULT latest.json (prod) -- a bare `curl | sh` install
# is byte-for-byte today's behavior. KOSMOS_UPDATE_CHANNEL=staging reads latest-staging.json, so a
# staging-channel install/update resolves the STAGING version and downloads the staging versioned
# artifact (kosmos-<staging-V>-arm64.tar.gz) below. update.js passes this through on an auto-update
# so the pointer it decided on and the pointer this installer reads are the SAME channel.
_PTR_FILE="latest.json"
[ "${KOSMOS_UPDATE_CHANNEL:-}" = staging ] && _PTR_FILE="latest-staging.json"
# file:// bases (thumb drives, the test harness) have no cache to bust,
# and a query string there is a different, missing filename.
BUST=""
case "$KOSMOS_RELEASE_BASE" in http://*|https://*) BUST=yes ;; esac
if [ -n "$BUST" ]; then
  _ptr="$(curl -fsSL -m 15 "$KOSMOS_RELEASE_BASE/$_PTR_FILE?nocache=$$" 2>/dev/null)" || _ptr=""
else
  _ptr="$(curl -fsSL -m 15 "$KOSMOS_RELEASE_BASE/$_PTR_FILE" 2>/dev/null)" || _ptr=""
fi
# ⚠️ The || guard is load-bearing under set -euo pipefail: a giant 200
# page full of version keys makes head close the pipe early, sed takes
# SIGPIPE, and the bare assignment would kill the run with no sentence
# (exit 141, measured). Every pointer shape must degrade to the
# versionless run, never to silence.
TARGET_VERSION="$(printf '%s' "$_ptr" | sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)" || TARGET_VERSION=""
if [ -n "$TARGET_VERSION" ]; then
  printf '  This run installs Kosmos %s.\n' "$TARGET_VERSION"
else
  printf '  (could not read the release pointer; installing what the download host serves)\n'
fi

step "Checking this computer."
# (A second Darwin check, deliberately: the one at the top of the file runs
# before the log exists and protects the shell from non-bash sh; this one
# puts the refusal INTO the narrated transcript for the supported flow.)
case "$(uname -s)" in
  Darwin) ;;
  *) die "Kosmos runs on macOS. This looks like $(uname -s)." ;;
esac
ARCH="$(uname -m)"
# ⚠️ Named refusal, not a mystery. Without this an Intel Mac asks the CDN for
# a bundle that does not exist and the experience is a bare "Could not
# install Kosmos" after a 404. Say the real reason in a sentence.
case "$ARCH" in
  arm64) ;;
  *) die "Kosmos needs a Mac with Apple silicon (M1 or newer). This Mac is $ARCH." ;;
esac
# ⚠️ THE macOS FLOOR IS GATED HERE, IN A SENTENCE, NOT DISCOVERED AT THE
# LAST STEP. The shipped Node runtime is built with minos 13.5 (measured
# with otool on the artifact), so on an older macOS the entire narrated
# install would succeed and then die at "Starting Kosmos." with a log
# nobody reads -- the exact opposite of the named-refusal rule above. The
# build gates its artifacts against this same floor, so the number here
# and the binaries cannot drift apart silently.
MACOS_FLOOR_MAJOR=13
MACOS_FLOOR_MINOR=5
_osver="$(sw_vers -productVersion 2>/dev/null || echo 0.0)"
[ -n "$_osver" ] || _osver="0.0"
_osmajor="${_osver%%.*}"
_osrest="${_osver#*.}"
_osminor="${_osrest%%.*}"
case "$_osmajor" in (*[!0-9]*|'') _osmajor=0 ;; esac
case "$_osminor" in (*[!0-9]*|'') _osminor=0 ;; esac
if [ "$_osver" = "0.0" ]; then
  die "Kosmos could not read this Mac's macOS version, so it cannot confirm it will run here. Kosmos needs macOS $MACOS_FLOOR_MAJOR.$MACOS_FLOOR_MINOR or newer."
fi
if [ "$_osmajor" -lt "$MACOS_FLOOR_MAJOR" ] || { [ "$_osmajor" -eq "$MACOS_FLOOR_MAJOR" ] && [ "$_osminor" -lt "$MACOS_FLOOR_MINOR" ]; }; then
  die "Kosmos needs macOS $MACOS_FLOOR_MAJOR.$MACOS_FLOOR_MINOR or newer. This Mac is on $_osver. Updating macOS in System Settings gets you there."
fi
info "macOS $_osver on $ARCH"

# ⚠️ CLAUDE CODE IS NOT GATED HERE ANY MORE, and this header used to say the
# opposite three lines above the block that says so. Kosmos starts every agent
# with the absolute path ~/.local/bin/claude (engine/create.js binPaths; a
# fresh Mac does not carry that folder on PATH, so `which claude` answers no
# on machines where it IS installed -- so the check must ask the path the
# product asks). Four states, and only one of them still acts:
#   at the path Kosmos uses            -> say so
#   installed, but somewhere else      -> say so, and LINK it (no bytes moved)
#   something there that cannot run    -> say so, carry on
#   genuinely absent                   -> say nothing, carry on
# Extracted as a function so the test runs the shipped code, like the
# tmux picker.
# 📌 NO SIZE FIGURE IS QUOTED IN THIS FILE, DELIBERATELY. The tree already
# carries two, both true when written: engine/connect.js says 281MB (measured
# 2026-08-12) and the vendor's manifest says 230,824,016 bytes today. A number
# in a comment is a number nobody updates, and the same argument applies to a
# comment as to a screen: if the size matters, read it from the manifest we
# already fetch for the checksum rather than from prose.
#
# 🔑 OBSERVES, INSTALLS NOTHING (#979, Josh's ruling 2026-08-26 10:32: "we
# assume that not everybody is going to have Claude Code... we're not forcing
# people to have Claude Code as part of the installer").
#
# 🛑 RENAMED FROM check_claude_code, DELIBERATELY. It used to be a gate with
# four arms: found-and-runnable -> ok; something-broken-at-the-path -> die;
# found-elsewhere -> symlink it; nothing -> `curl https://claude.ai/install.sh
# | sh` -> or die. Three of those four were the installer doing a provider's
# job, and Josh watched the fourth happen on a fresh Mac on 2026-08-26 at
# 14:45: a few hundred megabytes, no ask, no way to decline. A function still called `check_`
# that no longer gates is a name that lies, so the name went with the gate.
#
# ⚠️ AND IT CANNOT ASK. install/pkg-scripts/postinstall runs this script as
# `curl -fsSL "$0" | /bin/sh` under `launchctl asuser` -- no terminal, and
# stdin is this script's own bytes. A confirm step HERE is not hard, it is
# impossible. The ask belongs on the Connect screen, where a person is.
#
# ⚠️ NOTHING IS STRANDED BY THIS. engine/connect.js already probes for a
# runnable claude and, finding none, downloads it from the vendor, verifies
# the published per-platform SHA256, refuses an https->http redirect and runs
# its installer -- shipping since 2026-08-12. So a person who picks Claude
# still gets it; they just get it when they ask.
#
# 📌 THE LINK ARM STAYS. It moves no bytes and installs nothing; it makes a
# copy the person already installed usable, and without it they eat a fresh
# full download of software they have. See the arm itself for why the
# "runners.js will do it on Connect" reasoning was wrong.
#
# 📌 AGENT_WORKFORCE_CLAUDE_INSTALL_URL IS RETIRED HERE. It was the operator's
# mirror override for the download this function no longer performs. The
# surviving equivalent is engine/connect.js's
# AGENT_WORKFORCE_CLAUDE_DOWNLOAD_BASE. Named rather than silently dropped, so
# an operator who set it learns it moved instead of finding it ignored.
note_claude_code() {
  _claude_bin="${AGENT_WORKFORCE_CLAUDE_BIN:-$HOME/.local/bin/claude}"
  # -f AND -x, the #133 shape: a DIRECTORY at the path is executable in the -x
  # sense. -f follows symlinks, so a link to a real binary still passes.
  if [ -f "$_claude_bin" ] && [ -x "$_claude_bin" ]; then
    info "Claude Code found at $_claude_bin"
    return 0
  fi
  # ⚠️ EVERY ARM BELOW USED TO END THE INSTALL. None of them do now. Kosmos
  # installs; Claude is one provider among several and its absence, or a
  # broken file at its path, is a fact about that provider rather than a
  # reason nobody gets Kosmos.
  if [ -e "$_claude_bin" ] || [ -L "$_claude_bin" ]; then
    # ⚠️ ASKS ABOUT ELSEWHERE BEFORE GIVING UP. This arm used to return here,
    # which defeated the link arm below in the one case it exists for: a
    # broken link at the canonical path AND a working claude on PATH is
    # exactly the person who would otherwise re-download the whole binary
    # they already have. The old gate handled that pairing with a one-shot
    # `rm -rf … && ln -s …`; returning early silently dropped it.
    _claude_broken_elsewhere="$(command -v claude 2>/dev/null || true)"
    if [ -n "$_claude_broken_elsewhere" ]; then
      info "There is something at $_claude_bin that cannot run, and Claude Code is installed at $_claude_broken_elsewhere. Kosmos starts agents from $_claude_bin. Replace it and Kosmos will use it:"
      info "  rm -rf \"$_claude_bin\" && ln -s \"$_claude_broken_elsewhere\" \"$_claude_bin\""
      return 0
    fi
    info "There is something at $_claude_bin that cannot run (a broken link, a folder, or a file without execute permission). Kosmos will not use it. Remove it if you want Claude Code set up here:"
    info "  rm -rf \"$_claude_bin\""
    return 0
  fi
  _claude_elsewhere="$(command -v claude 2>/dev/null || true)"
  if [ -n "$_claude_elsewhere" ]; then
    # 🛑 THE LINK STAYS, and an earlier version of this branch removed it on
    # the grounds that engine/runners.js's vendor-external `linking` phase
    # would do it on Connect. CHECKED, and that was wrong twice: that phase
    # is on an unmerged branch, and even once it lands it is reachable only
    # through POST /api/runners/claude/install, which no screen calls.
    # engine/connect.js looks ONLY at the canonical path and never at
    # `command -v claude`, so a person with Claude Code at
    # /opt/homebrew/bin/claude would be told a link was coming and instead
    # get a fresh full download of something they already have.
    #
    # ⚠️ AND IT DOES NOT BREAK THE RULING. Josh's rule is that nothing
    # INSTALLS and nothing DOWNLOADS before a provider is chosen. A symlink
    # is neither: it moves no bytes and adds no software. It makes a copy the
    # person already chose to install usable, which is the opposite of
    # putting something on their Mac that they did not ask for.
    info "Claude Code is installed at $_claude_elsewhere, but Kosmos starts agents from $_claude_bin. Linking it there now."
    if mkdir -p "$(dirname "$_claude_bin")" \
      && ln -s "$_claude_elsewhere" "$_claude_bin" \
      && [ -f "$_claude_bin" ] && [ -x "$_claude_bin" ]; then
      info "Claude Code linked at $_claude_bin"
      return 0
    fi
    # Non-fatal now, where this used to die: one provider's convenience link
    # failing is not a reason nobody gets Kosmos.
    info "We could not link it, so Kosmos will download its own copy if you choose Claude. To avoid that, link it yourself:"
    info "  mkdir -p \"\$(dirname \"$_claude_bin\")\" && ln -s \"$_claude_elsewhere\" \"$_claude_bin\""
    return 0
  fi
  # 🛑 SILENT ON PURPOSE, and this is Josh's line rather than a preference.
  # 2026-08-26 14:59: *"If I immediately hit the page and, before I've even
  # picked a model (because I don't even use Claude, maybe I only use
  # OpenAI), it's telling me 'Oh I can't proceed because I don't have Claude
  # Code installed', it's like 'Why the hell would I install Claude Code?
  # That doesn't make any sense.'"*
  #
  # ⇒ The absence of ONE provider's runner is not the installer's news to
  # deliver, because at this moment nobody has chosen a provider. Kosmos
  # raises it on the Connect step for the provider the person actually picked,
  # with the size and a confirm. An `info` line here would be a smaller
  # version of exactly what he objected to.
  #
  # 🛑 THAT SENTENCE ENDED "AND NOWHERE ELSE" AND IT WAS FALSE.
  # engine/machine.js's installedCheck lists Claude Code beside tmux as a
  # thing the MACHINE needs, with no idea which provider anyone wants, and the
  # first-run checks screen paints it. That state was UNREACHABLE before this
  # change, because the install died first, so removing this gate is what
  # EXPOSES it. Claiming otherwise here would have sent the next reader
  # hunting a problem that had just been created two files away.
  # => Fixed on `machine-check-979c`, which must land with or before this
  # branch. Recorded rather than quietly narrowed.
  #
  # ⚠️ The other three arms DO speak, and the difference is deliberate: each
  # of them describes something ALREADY ON THIS MAC (found, unrunnable, or
  # somewhere unusual). That is a fact about their machine that explains what
  # Kosmos does later. "You do not have a thing you never asked for" is not.
  #
  # 📌 SILENT TO THE PERSON, NOT TO THE LOG. This file says the transcript is
  # "the one thing we ask a stranger to send us", and the commonest machine
  # state leaving no trace would make "Kosmos looked and found nothing"
  # indistinguishable from "Kosmos never looked". Josh's objection is to being
  # told about one provider on a SCREEN before choosing; a log line is not a
  # screen.
  # ⚠️ CARRIES THE RUN ID, like every other line in this file. This one writes
  # around the FIFO/awk writer, and the invariant is stated in capitals up top:
  # two overlapping runs interleave invisibly without it, and this transcript
  # is the one thing we ask a stranger to send us. A line whose whole purpose
  # is attributability was the one line nobody could attribute.
  # ⚠️ And 2>/dev/null FIRST: redirections apply left to right, so the other
  # order sends a failed-append error to the console, in the one arm that is
  # required to be silent.
  printf '[%s] %s\n' "$$" "note: no Claude Code at $_claude_bin and none on PATH; nothing installed (by design, #979)" 2>/dev/null >>"${LOG:-/dev/null}" || true
  return 0
}
note_claude_code
ok

# ⚠️ IDEMPOTENT, AND IT SAYS SO. Somebody who is not sure whether it worked will
# run it again. That must be safe and must not look like a failure.
if [ "$FRESH_INSTALL" = "no" ]; then
  info "Kosmos is already installed here. Updating it in place."
fi


# 🔑 A BUSY PORT IS SAID EARLY, AND THE INSTALL STILL FINISHES.
#
# It used to be discovered only at the very END of a first-time install: every
# step succeeded, and the last paragraph was the whole product the person saw.
# Saying it beside the macOS check costs three seconds and lands before the
# download, so nobody is surprised by it after investing.
#
# 🛑 BUT IT DOES NOT ABORT, AND AN EARLIER VERSION OF THIS DID. `tools/test-install.sh`
# encodes the considered design and caught it: "install onto an occupied port
# must say so, not print 'Kosmos is running', and must NOT open a browser onto
# the stranger's board" -- and the install EXITS 0. Aborting would leave a
# person with nothing installed over a port they can change with one word,
# which is worse than finishing and telling them how to start it elsewhere.
# The end-of-install paragraph already does that half.
#
# ⚠️ FRESH INSTALLS ONLY. On an UPDATE our own board is legitimately answering
# until the pause stops it, so this would fire on every update. The update path
# keeps its own check AFTER the stop, where it means "the stop did not work".
#
# 📌 Identity, not a bare 200: naming a stranger "a Kosmos board" hands out
# advice ('kosmos stop') that the very next command refuses.
if [ "$FRESH_INSTALL" = "yes" ]; then
  _portbody="$(curl -fsS -m 2 "http://127.0.0.1:$PORT/" 2>/dev/null)" || _portbody=""
  case "$_portbody" in
    *"Agent Workforce"*|*Kosmos*)
      # 🛑 IT SAYS WHAT IT SAW, NOT WHOSE IT IS. This read "(another account on
      # this Mac runs its own)", and Splinter found the third case within the
      # hour: an ORPHANED board of our own, left behind by an install test,
      # answering on the default port from a deleted worktree. A person sent to
      # look for a second account would not find one.
      # ⚠️ Same shape as the OTLP sentence two arms below and as "often another"
      # before it: the probe establishes THAT a Kosmos answers here, never WHOSE.
      info "note: a Kosmos board is already answering on port $PORT."
      info "      this install will finish; it will tell you how to start yours on another port."
      ;;
    "") ;;
    *)
      info "note: something else is already using port $PORT, so Kosmos will not be able to start there."
      # 🛑 NO NAMED CAUSE. This line used to say "$PORT is also the default for
      # OpenTelemetry collectors", which was TRUE when it was written and false
      # SIX MINUTES LATER, when the default moved off 4317 to 16180 in the very
      # commit that was fixing this class of wrong-cause sentence. 16180 is not
      # the default for anything, so there is no likely cause to name, and
      # naming one anyway is the exact defect that was being removed.
      # 🔑 An explanation is only true relative to a value; moving the value
      # rots it silently, and nothing greps for a sentence whose subject is a
      # variable. Found by Splinter on the wire.
      info "      this install will finish and tell you how to start Kosmos on another port."
      ;;
  esac
fi

mkdir -p "$KOSMOS_HOME" "$BIN_DIR" || die "Could not create $KOSMOS_HOME. Check that your home folder is writable."

# ---- tmux -------------------------------------------------------------------
# ⚠️ THE HARD PART, AND WHY IT IS SOLVED THIS WAY. macOS does not ship tmux, and
# Kosmos is built on it: the board reads what your agents are doing from tmux, so
# without it there is no product and it cannot degrade to a warning.
#
# We ship our own rather than asking for Homebrew, which would mean sudo and a
# multi-gigabyte developer-tools download in front of someone who was told this
# takes one line. Ours is ~2MB, lives in this folder, and touches nothing else.
# ⚠️ THE PAUSE HAPPENS BEFORE THE tmux SWAP, not between tmux and Kosmos:
# swapping tmux under a live board leaves a window where the binary the
# board polls does not exist (every agent reads as unknown), and a version
# change would strand the running tmux server on a protocol the new client
# cannot speak.
# #4356: this computer's choice ($KOSMOS_HOME/mode). The Mac app can change it WHILE this runs (the
# first screen's buttons, its menu's "Run agents on this computer"), so it is read again at each
# point this run decides something about the board, and the latest reading decides (reviews 5, 10,
# 13): _kosmos_board_decide, before the pause, before the start, before the launchd restart, and at
# the end, where a connect computer whose board is up is stopped. Every line below about the board
# comes from the reading current when it is printed.
_kosmos_mode_read() {
  _kosmos_mode_file=no; _kosmos_mode_word=""
  if [ -e "$KOSMOS_HOME/mode" ]; then
    _kosmos_mode_file=yes
    _kosmos_mode_word="$(cat "$KOSMOS_HOME/mode" 2>/dev/null)" || _kosmos_mode_word=""
  fi
}
# Why the board stays off, for the lines that say so: connect is a choice; an unreadable file is not
# (the app starts the board and asks at its next launch), so it gets its own words (review round 29).
_kosmos_off_why() {
  if [ "$_kosmos_mode_word" = connect ]; then printf 'while this computer connects to agents on another computer'
  else printf "until this computer's setup is chosen in the Kosmos app"; fi
}
_kosmos_board_decide() {
  _kosmos_mode_read
  if _kosmos_mode_keeps_board_off; then _kosmos_board_off=yes; else _kosmos_board_off=no; fi
}
_kosmos_mode_keeps_board_off() {
  [ "$_kosmos_mode_file" = yes ] || return 1
  case "$_kosmos_mode_word" in
    run|both) return 1 ;;
  esac
  return 0
}
# ---- #4818: a failed update puts back the board it paused --------------------
# The pause below stops the board and writes board.stopped, which launchd's KeepAlive keys on, so a run that
# FAILS after it left Kosmos off for good (Josh's laptop, 54 agents, 2026-09-30, until a hand-typed
# `kosmos start`), and an automatic update runs this same script. So: if the board was RUNNING before the
# pause (answering on its port, no board.stopped, a mode that runs it here), and the run then exits with a
# failure for any reason (a die, or set -e), the exit trap takes the marker away and starts it again, and
# says which version is back. A board the person had stopped stays stopped. Cleared once the new board has
# started, so a failure after that does not restart anything.
# BEGIN #4818 put-back
_kosmos_was_running=no
_kosmos_paused_board=no
_kosmos_put_board_back() {
  [ "$_kosmos_paused_board" = yes ] || return 0
  _kosmos_paused_board=no
  # Review 1: the mode is read AGAIN. A person who set this computer to connect elsewhere during the run (the app's
  # first screen) chose to keep its board off, and a mode file that became unreadable keeps it off too, as the
  # pause and the normal start already treat one; a failure after that must not start it.
  _kosmos_board_decide 2>/dev/null || true
  [ "${_kosmos_board_off:-no}" = yes ] && return 0
  rm -f "$KOSMOS_HOME/board.stopped" 2>/dev/null || true
  # The start's own verdict (review 5): it waits for the board itself, and a second short probe here told a busy
  # board's person it "could not be started" while it was running.
  if [ -f "$KOSMOS_HOME/bin/kosmos" ] && [ -x "$KOSMOS_HOME/bin/kosmos" ] \
     && KOSMOS_RECLAIM_BUSY=1 "$KOSMOS_HOME/bin/kosmos" start --force >/dev/null 2>&1; then
    _kosmos_back_v="$(sed -n 's/^[[:space:]]*"version":[[:space:]]*"\([^"]*\)".*/\1/p' "$KOSMOS_HOME/app/package.json" 2>/dev/null | head -1)" || _kosmos_back_v=""
    # The version on disk, which after a failure past the file swap may not be the one from before the update.
    printf '  Kosmos is running again (%s). This update did not finish; it is safe to paste the install line again.\n\n' "${_kosmos_back_v:-version unrecorded}" >&2
  else
    printf '  Kosmos was paused for this update and could not be started again. Open the Kosmos app, or run: kosmos start\n\n' >&2
  fi
}
_kosmos_on_exit() {
  _kosmos_exit_rc=$?
  if [ "$_kosmos_exit_rc" -ne 0 ]; then _kosmos_put_board_back || true; fi
}
trap '_kosmos_on_exit' EXIT
# Review 2: a hang-up (the Terminal window closed during the download) or a TERM ran the EXIT trap with status 0, so the
# put-back was skipped and the board stayed off. Those signals now end the run as a failure. (Ctrl-C already did.)
trap 'exit 1' HUP TERM
# END #4818 put-back

_kosmos_board_decide
if [ "$FRESH_INSTALL" = "no" ] && [ -f "$KOSMOS_HOME/bin/kosmos" ] && [ -x "$KOSMOS_HOME/bin/kosmos" ]; then
  if _kosmos_mode_keeps_board_off; then info "making sure Kosmos is paused for the update"; else info "pausing Kosmos for the update"; fi
  # #4818: MEANT to be running before the pause, so a failed run puts it back: no board.stopped and a mode that runs
  # it here, the person's own settings (review 5). Not whether it answers or has a live pid: a board busy with many
  # agents misses a probe (review 4), and one crash-looping or mid-restart under launchd has no live pid for a moment,
  # yet `kosmos stop` writes board.stopped either way, so a later failure left it off. Another install's board or
  # another app on the port cannot use this: the put-back is armed only after those dies, below.
  if ! _kosmos_mode_keeps_board_off && [ ! -e "$KOSMOS_HOME/board.stopped" ]; then
    _kosmos_was_running=yes
  fi
  "$KOSMOS_HOME/bin/kosmos" stop --force >/dev/null 2>&1 || true
  # Did the stop actually work? A POST-CONDITION of the line above, which is
  # why it needs the binary to exist. Fresh installs get their own check far
  # earlier, where it is a precondition instead.
  _pausebody="$(curl -fsS -m 2 "http://127.0.0.1:$PORT/" 2>/dev/null)" || _pausebody=""
  case "$_pausebody" in
    *"Agent Workforce"*|*Kosmos*)
      # #964: is the board that answered actually OURS? The check above matches ANY
      # Kosmos-shaped body, so on a multi-account Mac a DIFFERENT install's board
      # (or another account's) legitimately holding this port reads as "our board
      # will not pause" -- and the "kosmos stop" advice is then a no-op, because our
      # own board is already dead. A pre-#910 stale install records port 16180, which
      # a second Kosmos can now hold, so this is a real returning-user shape (the
      # aged-specimen walk that found this, 2026-08-26). Our install records its
      # board's pid in board.pid; whatever answers on $PORT is ours only if that pid
      # is the running board. Only OUR-board-will-not-pause takes the #2055 abort
      # streak + the "kosmos stop" die; a foreign board gets actionable port advice.
      #
      # STRICTER THAN A BARE kill -0. The #964 target is a returning user whose board
      # died weeks ago on a machine that has since REBOOTED, so the stale board.pid
      # NUMBER has very likely been reused by an unrelated live process -- kill -0
      # would return 0 and wrongly take the "our board" branch, re-arming the exact
      # forever-loop this fixes. Match the command against THIS install's full
      # server path, mirroring the BOARD_OURS check later in this file (the one whose
      # comment warns "a recycled pid, or another install's live server behind a
      # stale pidfile, must not read as ours"); do not "align" it down to kill -0.
      _ourboard=no
      if [ -f "$KOSMOS_HOME/board.pid" ]; then
        _ourpid="$(cat "$KOSMOS_HOME/board.pid" 2>/dev/null || true)"
        case "$_ourpid" in
          ''|*[!0-9]*) ;;
          *)
            case "$(/bin/ps -ww -p "$_ourpid" -o command= 2>/dev/null)" in
              *"$KOSMOS_HOME/app/server.js"*) _ourboard=yes ;;
            esac
            ;;
        esac
      fi
      if [ "$_ourboard" = yes ]; then
        # OUR board is genuinely running and did not pause -- the #2055 behavior.
        # #2055: on the AUTOMATIC update path this die is SILENT -- the board's own
        # in-process updater spawned this curl|sh, so the message goes to stderr /
        # install.log and nobody reads it. One machine aborted here 155 times before
        # anyone noticed. Record the abort durably (in the same logs/ dir the board
        # reads install.status from) with a CONSECUTIVE count, so the board can surface
        # "this machine keeps failing to update". The count is cleared below once an
        # update gets past the pause, so a machine that recovers stops showing it.
        _abortf="$LOG_DIR/update-abort"
        _abortn=0
        if [ -f "$_abortf" ]; then
          _abortn="$(sed -n 's/^count=\([0-9][0-9]*\)$/\1/p' "$_abortf" 2>/dev/null || true)"
        fi
        case "$_abortn" in ''|*[!0-9]*) _abortn=0 ;; esac
        _abortn=$((_abortn + 1))
        { printf 'count=%s\nreason=board-would-not-pause\nport=%s\nts=%s\n' \
            "$_abortn" "$PORT" "$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo unknown)" \
            > "$_abortf"; } 2>/dev/null || true
        die "A Kosmos board is still running on port $PORT and could not be paused for the update. Stop it first ('kosmos stop', or quit whatever started it), then paste the install line again."
      else
        # #964: our own board is not running, so a DIFFERENT Kosmos is holding this
        # port. "kosmos stop" would do nothing (ours is already stopped), so name the
        # real situation and give an action that can actually unstick it: quit that
        # board, or reinstall on a free port. NOT recorded as a board-would-not-pause
        # abort -- that streak is about OUR board, and inflating it here would mask a
        # machine whose own board really cannot pause.
        # ⚠️ ONE FALSE-NEGATIVE, the same fail-safe residual BOARD_OURS carries: if OUR
        # board is genuinely alive and serving but board.pid is absent/stale, we land
        # here and the message wrongly says "your board is not running". It is still
        # fail-safe (dies, writes nothing, no brick), and it only fires after `kosmos
        # stop` already failed to pause a board on our port, so the window is narrow --
        # but the "quit it" advice could nudge that user at their own live board. Fixing
        # it needs a stronger own-board signal than board.pid; out of scope here.
        # #4356: on a computer whose choice keeps its board off (connect), the pause has nothing to
        # protect: this install's board is not running and will not be started, and the other
        # board on the port is not ours to pause. Refusing would make the install line, a connect
        # computer's only way to update, fail every time on a shared Mac (review round 19).
        if _kosmos_mode_keeps_board_off; then
          info "another Kosmos is answering on port $PORT; it is not this install's, and this install does not start a board here now, so it is left alone"
        else
          die "Another Kosmos is answering on port $PORT, but this install's own board is not running -- so 'kosmos stop' would do nothing and the update cannot pause it. That board belongs to a different install or account on this computer. Quit it, or reinstall on a free port by running the install line with KOSMOS_PORT set to a different number."
        fi
      fi
      ;;
    "") ;;
    *)
      die "Another app on this computer is using port $PORT, which Kosmos needs. Quit that app, then paste the install line again."
      ;;
  esac
  # #4818: the pause held (the board no longer answers), so from here a failure puts back a board that was running.
  # Armed HERE, before the port wait below (review 3): a survivor still holding the port, or a hang-up during that wait,
  # used to leave the board off with board.stopped written. Not armed on the three dies above: our board still running,
  # another install's board, or another app on the port (starting ours there would collide).
  _kosmos_paused_board="$_kosmos_was_running"
  # ⚠️ GONE BY PORT, not merely quiet over HTTP: a listener that stopped
  # answering the probe (mid-shutdown, wedged, or simply not speaking
  # HTTP) still holds the port, and the final start would then find a
  # healthy-looking board and quietly leave the OLD process serving
  # (the exact after-state found on Josh's machine, 2026-08-24: a board
  # outside launchd's supervision on the prior version). A survivor is
  # named by pid. No lsof on this Mac degrades to the probe above.
  if command -v lsof >/dev/null 2>&1; then
    # Ten seconds of grace: a node board draining on a busy Mac can hold
    # the listener a few seconds past the stop, and a die here on an
    # honest shutdown would be this guard crying wolf.
    # ⚠️ EVERY lsof CALL WEARS AN || true: this script runs under set -e,
    # and lsof answers exit 1 for the GOOD case (nothing listening), so
    # the bare substitution killed the run silently at "pausing" (found
    # by the harness's update pass going from green to a log that just
    # stops). The good case must never be the fatal one.
    _tries=0; _pids=""
    while [ "$_tries" -lt 10 ]; do
      _pids="$(lsof -tiTCP:"$PORT" -sTCP:LISTEN 2>/dev/null || true)"
      if [ -z "$_pids" ]; then break; fi
      _tries=$((_tries + 1)); sleep 1
    done
    if [ -n "$_pids" ]; then
      _pids="$(printf '%s' "$_pids" | tr '\n' ' ' | sed 's/ *$//')"
      die "A process is still holding port $PORT after the pause (pid $_pids). Quit it (or run 'kill $_pids'), then paste the install line again."
    fi
  fi
  # #2055: got past the pause -- the update is proceeding, so the consecutive
  # board-would-not-pause abort streak is broken. Clear the marker so a machine
  # that recovers stops surfacing the notice. NOTE the scope: this clears only the
  # PAUSE-abort streak; it does NOT assert the update SUCCEEDED. A later failure (a
  # 404, a checksum refusal, a failed swap) is a different signal (install.status /
  # the #1728 in-flight marker), so clearing here on passing the pause is correct.
  rm -f "$LOG_DIR/update-abort" 2>/dev/null || true
fi

step "Setting up the pieces Kosmos needs."
# ⚠️ FETCHED ON EVERY RUN, not only the first. The old guard skipped this
# whole step when a tmux was already present, which froze every machine at
# whatever tmux its FIRST install shipped -- no path to ever deliver a fix.
# The staged swap makes re-fetching safe, and the download is ~700KB.
info "installing a private copy of tmux (about 2MB, nothing system-wide)"
# On a release this fetches the checksum-verified bundle from the release
# URL (the binaries inside carry ad-hoc signatures; nothing here is Apple-
# signed, and saying "signed" would overclaim). Kept as a function so the
# clean-machine test can point it at a local file.
fetch_tmux "$KOSMOS_HOME/tmux" || die "Could not set up the terminal manager. The lines above say why, and whether trying again can help."
ok

# ⚠️ TERMINFO IS PINNED RATHER THAN TRUSTED. The bundled ncurses carries a
# compiled-in path to the terminfo database from the machine it was built on,
# which will not exist here. macOS ships its own at /usr/share/terminfo and
# ncurses is expected to fall back to it, but "expected to" is doing work in that
# sentence and this is the machine where it would fail. Pinning it converts an
# assumption into a fact, for free.
export TERMINFO_DIRS="${TERMINFO_DIRS:-/usr/share/terminfo}"

# ---- providers: deliberately NOT here -----------------------------------------
# ⚠️ THE INSTALLER NEVER MENTIONS A PROVIDER BY NAME, AND THAT IS A RULE RATHER
# THAN AN OMISSION. Decided with Josh, 2026-08-12.
#
# An earlier version of this file checked for Claude Code here and reported on
# it. Harmless today, when Claude is the only option, and a trap the moment there
# is a second one: the assumption spreads, and adding OpenAI then means either
# bloating this one line toward 700MB or bolting on a separate mechanism.
#
# So this script installs the PLATFORM: a runtime, a terminal multiplexer, and
# Kosmos. **Choosing a provider inside the app is what installs that provider**,
# which is also the click that signs you into it.
#
# Three things that gets us:
#   1. The terminal step drops to ~130MB instead of ~400MB. In a room of thirty
#      people watching a black screen, that difference is the whole experience.
#   2. The large download happens inside our UI, where a real progress bar can
#      live, instead of in a terminal where silence reads as a hang.
#   3. Nobody downloads a provider they will never use.
#
# ⚠️ What it costs, so nobody is surprised: the user is NOT finished when this
# script finishes. The provider screen has to survive being quit and resumed
# mid-download, because somebody will close the laptop.

# ---- kosmos itself ----------------------------------------------------------
step "Installing Kosmos."
# ⚠️ THE RUNNING BOARD STOPS BEFORE THE SWAP, or the update does not happen.
# The swap replaces app/ and runtime/ on disk, but the OLD process keeps
# serving from memory, and the final `kosmos start` sees a healthy port and
# returns without starting anything -- so the installer would print
# "Kosmos is running" while the machine keeps executing the previous
# version until a reboot. Stopping first also closes the window where the
# live server's web/index.html is deleted out from under it mid-install.
# (The board was already paused above, before the tmux swap; a refused
# pause has already refused the whole update in a sentence.)
install_kosmos "$KOSMOS_HOME" || die "Could not install Kosmos. The line above says why. It is safe to paste the install line and try again."
ln -sfn "$KOSMOS_HOME/bin/kosmos" "$BIN_DIR/kosmos" || die "Could not place the kosmos command in $BIN_DIR. Check that your home folder is writable."
info "installed to $KOSMOS_HOME"
ok

# ⚠️ WIRED, not narrated. A binary in ~/.local/bin is useless to somebody
# whose shell does not look there, and the note this used to print reached
# nobody: measured 2026-08-18, the person AND every agent on the machine got
# "command not found" from the taught command, the agents silently (their
# failure happens before the engine, so nothing draws it anywhere). zsh is
# the macOS default login shell, so the line lands in ~/.zprofile (created
# if absent), marker-guarded so reruns never duplicate it; --uninstall
# removes exactly the two lines this writes and nothing else. A profile we
# cannot write degrades to the old honest note, never to silence.
PROFILE_FILE="${KOSMOS_PROFILE_FILE:-$HOME/.zprofile}"
# A relative profile path would resolve against whatever directory each
# run happens to start from, so install and uninstall could edit two
# different files (the same reason KOSMOS_HOME refuses relative paths).
case "$PROFILE_FILE" in
  /*) ;;
  *) info "note: KOSMOS_PROFILE_FILE must be an absolute path; skipping the shell profile"
     PROFILE_FILE="" ;;
esac
# ⚠️ A SANDBOXED RUN NEVER TOUCHES THE REAL PROFILE. Same keying as the
# lsregister gate: any app-dir override means a test harness, and the only
# profile such a run may write is one it names explicitly. The first
# harness run after this feature leaked a sandbox bin path into the
# operator's real ~/.zprofile; this gate is that measurement.
if [ -n "${KOSMOS_APP_DIR:-}${KOSMOS_SYS_APP_DIR:-}${KOSMOS_HOME_APP_DIR:-}" ] && [ -z "${KOSMOS_PROFILE_FILE:-}" ]; then
  PROFILE_FILE=""
fi
case ":$PATH:" in
  *":$BIN_DIR:"*) ;;
  *)
    if [ -z "$PROFILE_FILE" ]; then
      info "skipping the shell profile (sandboxed run, no profile named)"
    elif [ -z "${KOSMOS_PROFILE_FILE:-}" ] && [ -n "${SHELL:-}" ] && [ "${SHELL##*/}" != "zsh" ]; then
      # An EXPLICIT KOSMOS_PROFILE_FILE outranks this hedge: a bash user
      # pointing at their own ~/.bash_profile asked for exactly this write.
      # ⚠️ The claim must not outrun the file: ~/.zprofile is read by zsh
      # only, and a bash/fish login shell would get "success" and a command
      # that still fails -- the silent class this whole step exists to end.
      # An empty $SHELL falls through to wiring: the macOS default is zsh.
      info "note: typing 'kosmos' in Terminal will not work yet on this computer (your login shell is ${SHELL##*/}, and this installer only knows how to wire zsh); the app icon step below and the closing lines cover how to open Kosmos"
    else
      case "$BIN_DIR" in
        *"
"*|*'"'*|*'$'*|*'`'*|*'\'*|*':'*)
          # Same class as the KOSMOS_HOME guard above: these characters
          # would corrupt (or execute inside) a file sourced at every
          # login. Refuse the write, keep the honest note.
          info "note: typing 'kosmos' in Terminal will not work yet on this computer (the bin folder's name contains a character unsafe to write into ${PROFILE_FILE##*/}); the app icon step below and the closing lines cover how to open Kosmos"
          ;;
        *)
          # "Already wired" requires BOTH halves AND their adjacency: the
          # export-shaped line directly after the marker, anchored. A
          # profile carrying the marker with the export hand-deleted or
          # commented out must fall through and repair the functional
          # half, not report wired forever -- the silent class this step
          # ends. (An unanchored grep matched '# export ...' and any
          # person-owned export of that shape anywhere in the file.)
          # STICKY across every marker occurrence: a scan that latched on
          # the first marker never recognized the repaired pair below an
          # orphan, so each rerun appended another pair, unbounded.
          if [ -f "$PROFILE_FILE" ] \
             && awk -v m="$PATH_MARKER" '
                  $0 == m { f = 1; next }
                  f == 1 { if ($0 ~ /^export PATH=".*:\$PATH"$/) ok = 1; f = 0 }
                  END { exit (ok == 1) ? 0 : 1 }
                ' "$PROFILE_FILE" 2>/dev/null; then
            # No works-claim here: the wired export names whatever bin dir
            # the EARLIER install used, which this run cannot vouch for.
            info "the kosmos command is already wired into ${PROFILE_FILE##*/}"
          elif { printf '\n%s\n%s\n' "$PATH_MARKER" "$PATH_LINE" >> "$PROFILE_FILE"; } 2>/dev/null; then
            info "wired ${PROFILE_FILE##*/} so typing 'kosmos' works in NEW Terminal windows (windows already open keep their old PATH)"
            if [ -n "${KOSMOS_PROFILE_FILE:-}" ]; then
              info "note: run --uninstall with the same KOSMOS_PROFILE_FILE so the line comes off with it"
            fi
          else
            info "note: typing 'kosmos' in Terminal will not work yet on this computer (could not write ${PROFILE_FILE##*/}); the app icon step below and the closing lines cover how to open Kosmos"
          fi
          ;;
      esac
    fi
    ;;
esac

# ---- the front door -----------------------------------------------------------
# ⚠️ AN ICON IS HOW A NON-TECHNICAL PERSON OWNS SOFTWARE, and without one this
# whole install produces a URL. Josh, 2026-08-12: "Typing some huge, super
# technical-looking 127.0.0.1:4317 is super scary looking for a non-technical
# person... Nobody will ever come back to this after the install essentially."
# He is right, and it would have been the quiet reason the product got installed
# once and never opened again.
#
# ⚠️ AND THIS DOES NOT REOPEN THE SETTLED "NO .app" DECISION. The launch
# decision of 2026-08-11 ruled out a DOWNLOADABLE app, because an unsigned app that arrives from the
# internet carries a quarantine attribute and Gatekeeper shows the "unidentified
# developer" block, which needs an Apple developer account to clear.
#
# An app BUILT HERE is never downloaded, so it is never quarantined, so
# Gatekeeper never runs. MEASURED: a locally-created .app has no extended
# attributes at all and macOS reports it as a proper application bundle. We still
# ship one terminal line. That line just leaves an icon behind.
# ⚠️ STAGED, LIKE EVERY OTHER SWAP IN THIS FILE. The bundle is built complete
# in a hidden sibling and renamed into place, because a build that dies
# between mkdir and the launcher write used to leave a launcher-less husk at
# the real path -- which every later run's ownership check read as foreign
# (divert forever) and which --uninstall refused to touch for the same
# reason: a permanently wedged Applications slot the documented uninstall
# could not reach, on the file whose header promises reversibility. The
# stage is cleaned on every failure path, and uninstall sweeps stage
# residue too.
make_app() {
  # ⚠️ TWO STATEMENTS, NOT ONE. `local app="$1" target="$app/Contents"` looks fine
  # and fails under `set -u`: bash does not make `app` visible to later
  # assignments in the SAME `local` statement, so `$app` is unbound and the whole
  # step dies. Measured, after the installer reported "app: unbound variable" and
  # created nothing.
  local app="$1"
  local appdir stage
  appdir="$(dirname "$app")"
  stage="$appdir/.Kosmos.app.stage.$$"
  # Sweep SIBLING pids too, the same opening move as fetch_tmux and
  # install_kosmos and for the same reason: every interrupted run would
  # otherwise leave a complete hidden bundle copy accumulating under a
  # fresh pid until an uninstall the user may never run. WITH the
  # ownership proof, because an aside in a SHARED folder can be another
  # account's only surviving icon; a foreign or unprovable residue is
  # skipped silently here (the uninstall names them). (Same accepted
  # two-accounts-at-the-same-instant race as the probe sweep.)
  local _res
  for _res in "$appdir"/.Kosmos.app.stage.* "$appdir"/.Kosmos.app.old.*; do
    { [ -e "$_res" ] || [ -L "$_res" ]; } || continue
    if bundle_is_ours "$_res"; then
      rm -rf "$_res" 2>/dev/null || true
    fi
  done
  rm -rf "$stage" 2>/dev/null || true
  # (The own-pid stage and aside this run creates are cleaned WITHOUT the
  # ownership predicate, deliberately: a partial stage is unprovable by
  # construction, and refusing to clean our own current-run scratch would
  # leave it forever. The predicate gates only OTHER pids' residue.)
  # ⚠️ mkdir WITHOUT -p, by absolute path, as the stage's first act: -p
  # follows a symlink planted at this predictable name and would build the
  # bundle at the link's target, then install the link itself as
  # Kosmos.app. A bare mkdir fails on ANYTHING already at the path,
  # including a symlink slipped in after the rm above. (In /Applications
  # the planter is already an admin, so this is hardening rather than a
  # live hole; it costs one word.)
  /bin/mkdir "$stage" 2>/dev/null || return 1
  if ! build_app_bundle "$stage"; then
    rm -rf "$stage" 2>/dev/null || true
    return 1
  fi
  # ⚠️ THE OLD BUNDLE IS RENAMED ASIDE, NEVER rm -rf'd IN PLACE. rm -rf is
  # depth-first and can die partway (one root-owned nested directory is
  # enough), which GUTS the bundle -- launcher gone, husk left -- and a
  # launcher-less husk is unprovable to every later ownership check:
  # installs divert forever and uninstall refuses it. A rename cannot
  # partially gut a tree, so the visible Kosmos.app is only ever complete
  # (old) or complete (new). The aside copy is deleted best-effort and its
  # name is swept by --uninstall.
  local aside
  aside="$(dirname "$app")/.Kosmos.app.old.$$"
  rm -rf "$aside" 2>/dev/null || true
  if [ -e "$app" ] || [ -L "$app" ]; then
    # ⚠️ RE-VERIFIED IMMEDIATELY BEFORE THE RENAME: ownership was proved
    # at resolve time, and in a shared folder the occupant can change
    # between then and now. The displaced bundle gets deleted, so the
    # proof must be contemporaneous with the displacement, or the header
    # sentence "only ever replaces a Kosmos icon it can prove it created"
    # holds only usually.
    if ! bundle_is_ours "$app"; then
      rm -rf "$stage" 2>/dev/null || true
      return 1
    fi
    if ! mv "$app" "$aside" 2>/dev/null; then
      rm -rf "$stage" 2>/dev/null || true
      return 1
    fi
  fi
  if ! mv "$stage" "$app" 2>/dev/null; then
    # Put the old bundle back, best-effort -- a failed swap must not leave
    # the slot empty when a working icon existed seconds ago -- and if
    # even that fails, SAY where the icon went instead of losing it in
    # silence.
    if [ -e "$aside" ] || [ -L "$aside" ]; then
      mv "$aside" "$app" 2>/dev/null \
        || info "note: the previous Kosmos icon could not be put back; it is in the hidden folder $aside"
    fi
    rm -rf "$stage" 2>/dev/null || true
    return 1
  fi
  rm -rf "$aside" 2>/dev/null \
    || info "note: could not remove the leftover hidden folder $aside; drag it to the Trash to finish."

  # ⚠️ TELL macOS THE APP EXISTS. A freshly created bundle is not in the
  # LaunchServices database, and until it is, it can show a generic icon or
  # behave oddly when opened. Measured: straight after creation, lsregister knew
  # nothing about it.
  #
  # On a machine that has run this before, this is also what makes a REPLACED
  # bundle pick up a new icon instead of the cached old one. Failure here is not
  # fatal, the app still works, so it never aborts the install.
  # ⚠️ NEVER FROM A SANDBOX: lsregister writes the operator's REAL
  # machine-global LaunchServices database, under the production bundle
  # id. Measured after harness runs: dozens of dead mktemp paths
  # registered against com.chaoskosmos.kosmos. Any override set means a
  # harness, and a harness must leave that database alone.
  if [ -z "${KOSMOS_APP_DIR:-}${KOSMOS_SYS_APP_DIR:-}${KOSMOS_HOME_APP_DIR:-}" ]; then
    local lsreg=/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister
    # ⚠️ TOUCH BEFORE REGISTERING. MEASURED (Josh's clean-machine install,
    # 2026-08-17): app present, Get Info previews the icon, the Dock draws
    # the generic tile. MEASURED on this machine (2026-08-17): mv preserves
    # a directory's mtime, so the .app arrives with the stage's timestamp
    # rather than a fresh one. HYPOTHESIS, unverifiable here: icon consumers
    # keying a re-read off that mtime never look again. The touch is the non-invasive subset of the
    # manual remedy that ships (touch + register, WITHOUT the killall Dock
    # a person can run); if the Dock's in-session cache was the operative
    # ingredient, a clean install may still draw generic and this area is
    # NOT ruled out -- the next clean-machine run is the first real test.
    # -c so the only thing this line can ever do is bump a time.
    /usr/bin/touch -c "$app" 2>/dev/null || true
    [ -f "$lsreg" ] && [ -x "$lsreg" ] && "$lsreg" -f "$app" >/dev/null 2>&1 || true
  fi
  return 0
}

build_app_bundle() {
  # ⚠️ EVERY STEP CARRIES ITS OWN `|| return 1`. This function runs as an `if`
  # condition, and that DISABLES `set -e` for its whole body (measured: a
  # failing mkdir inside it did not abort, and the caller printed success
  # over a bundle that was never created). The fallback branch at the call
  # site is only reachable if failures are returned by hand.
  local app="$1"
  local target="$app/Contents"
  # The version the app reports is the one that was installed, read from the
  # installed bundle itself, so the plist cannot drift from package.json.
  # The baked uid is captured and VALIDATED before the heredoc: an empty
  # substitution would bake `!= ""`, which is always true, and the icon
  # would refuse every account including the installing one, forever.
  # (The same shape as the empty-ver guard below, and the same lesson as
  # the retired under-HOME proxy that degenerated when HOME was empty.)
  local owner_uid
  owner_uid="$(/usr/bin/id -u)" || owner_uid=""
  case "$owner_uid" in
    ''|*[!0-9]*) return 1 ;;
  esac
  local ver
  ver="$(KOSMOS_PKG="$KOSMOS_HOME/app/package.json" \
    "$KOSMOS_HOME/runtime/bin/node" -p 'JSON.parse(require("fs").readFileSync(process.env.KOSMOS_PKG,"utf8")).version' 2>/dev/null)" || ver="0.0.0"
  [ -n "$ver" ] || ver="0.0.0"
  mkdir -p "$target/MacOS" "$target/Resources" || return 1

  # ⚠️ THE ARCHITECTURE IS DECLARED, because the executable is a shell
  # script: LaunchServices cannot read an arch from a non-Mach-O file and
  # on Apple silicon it then demands Rosetta before opening the app at
  # all (measured on the first real desktop click, 2026-08-13: "To open
  # Kosmos, you need to install Rosetta" for a fully native app).
  # LSArchitecturePriority arm64 + LSRequiresNativeExecution tell it the
  # truth and the prompt never appears.
  cat > "$target/Info.plist" <<PLIST || return 1
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>CFBundleName</key><string>Kosmos</string>
  <key>CFBundleDisplayName</key><string>Kosmos</string>
  <key>CFBundleIdentifier</key><string>com.chaoskosmos.kosmos</string>
  <key>CFBundleExecutable</key><string>Kosmos</string>
  <key>CFBundlePackageType</key><string>APPL</string>
  <key>CFBundleShortVersionString</key><string>$ver</string>
  <key>CFBundleVersion</key><string>$ver</string>
  <key>CFBundleIconFile</key><string>Kosmos</string>
  <key>LSArchitecturePriority</key><array><string>arm64</string></array>
  <key>LSRequiresNativeExecution</key><true/>
  <key>LSMinimumSystemVersion</key><string>$MACOS_FLOOR_MAJOR.$MACOS_FLOOR_MINOR</string>
  <key>LSUIElement</key><false/>
  <!-- #2810: "Open Terminal" runs osascript to tell Terminal.app to attach the
       agent's tmux session. The board LaunchAgent below carries
       AssociatedBundleIdentifiers=com.chaoskosmos.kosmos, so macOS attributes
       that Apple-event request to THIS bundle for its Automation (TCC) decision.
       Without a usage-description string on the bundle, macOS does not prompt and
       silently denies with -1743 ("Not authorized to send Apple events to
       Terminal"), which is exactly what every agent hit after 0.6.56. This string
       is the text the one-time "Kosmos wants to control Terminal" prompt shows;
       once the person allows it, the grant persists for this Developer ID
       signature across updates.
       #3113: this ONE NSAppleEventsUsageDescription is SHARED (macOS allows only
       one per bundle) and serves the RUNTIME automation paths: Open Terminal
       (control Terminal) AND an agent driving Terminal/System Events under its
       bundled tmux at first action, which is how tmux acquires its own
       Accessibility row. (#3282 removed the onboarding pre-register that used to
       fire this ahead of time; the grant is now acquired at runtime, but the
       shared string still covers both uses.) Do NOT re-narrow it to Open-Terminal
       only -- the tmux runtime automation still needs it. -->
  <!-- #4409: the mic button in the composers. Each string is the ONE plain line macOS shows in its
       prompt. Both are REQUIRED before the app may ask: with either missing, macOS kills the app at the
       request (the native bridge checks for both and refuses instead). The entitlement that lets the
       hardened-runtime binary reach the mic is on its signature (native-app/kosmos-app.entitlements). -->
  <key>NSMicrophoneUsageDescription</key><string>Kosmos listens only while the microphone button is on, and turns your words into text on this computer. No audio is kept or sent anywhere.</string>
  <key>NSSpeechRecognitionUsageDescription</key><string>Kosmos turns what you say into text on this computer, only while the microphone button is on. No audio is kept or sent anywhere.</string>
  <key>NSAppleEventsUsageDescription</key><string>Kosmos uses this so you can allow tmux (the tool that runs your agents) in your Accessibility settings, and to open a Terminal window with your agent's session when you choose Open Terminal.</string>
</dict></plist>
PLIST

  # ⚠️ A COMPILED BINARY NOW (#677), not a heredoc script -- built and
  # Developer ID signed once, by tools/build-kosmos-bundle.sh, never
  # per-install: it is byte-identical across every Mac it lands on. It
  # starts the board if not running (native-app/main.swift's startBoard(),
  # `bin/kosmos start` directly -- NOT `kosmos open`, which also pops a
  # browser tab; this window IS what `open` would have opened), health-
  # checked and identified the same way `kosmos start` always has. If that
  # fails, or a different account clicked the shared icon (#664), the
  # binary shows its own dialog instead of opening a dead page -- the
  # same two sentences the old bash launcher's osascript calls used,
  # verified verbatim, now native NSAlerts (native-app/main.swift's
  # resolveInstall/startBoard/showStartupFailureAlert/
  # showForeignAccountAlert; see .claude/plans/native-app-677.md phase 2).
  # Existence and executability checked before the copy: a bundle that
  # shipped app/ without it would otherwise fail silently here and
  # produce an Info.plist naming an executable that does not exist.
  [ -f "$KOSMOS_HOME/app/bin/kosmos-app" ] && [ -x "$KOSMOS_HOME/app/bin/kosmos-app" ] || return 1
  cp "$KOSMOS_HOME/app/bin/kosmos-app" "$target/MacOS/Kosmos" || return 1
  chmod +x "$target/MacOS/Kosmos" || return 1

  # ⚠️ THE PER-INSTALL VALUES the old heredoc baked into shell text now
  # live here instead, because the binary itself never changes and reads
  # them at launch (KosmosInstallConfig in native-app/main.swift). ONE
  # LINE, no extra whitespace: bundle_is_ours greps this file for the
  # anchored token `"kosmosHome":"<home>"` byte for byte, and a
  # differently-formatted encoder output (a space after the colon, a
  # trailing newline before the value ends) would silently break that
  # ownership proof for every bundle built this way from now on.
  # owner_uid was already validated non-empty and all-digits above; PORT
  # is validated the same way earlier in this file.
  printf '{"kosmosHome":"%s","ownerUid":%s,"port":%s}' \
    "$KOSMOS_HOME" "$owner_uid" "$PORT" > "$target/Resources/kosmos-install.json" || return 1

  # The icon is optional so the installer never fails for the want of
  # artwork; it ships inside the bundle at app/assets/ (the gold-K
  # Kosmos.icns landed 2026-08-13, macOS-shaped). (CFBundleIconFile
  # pointing at a file that is absent is harmless: macOS falls back to
  # the generic icon either way. A Dock that already pins Kosmos may
  # keep its cached tile until the Dock restarts; that is the Dock's
  # cache, not a bad icns.)
  [ -f "$KOSMOS_HOME/app/assets/Kosmos.icns" ] && cp "$KOSMOS_HOME/app/assets/Kosmos.icns" "$target/Resources/Kosmos.icns"
  return 0
}

step "Adding Kosmos to your Applications."
resolve_app_dir
# ⚠️ THE ONE DIALOG THIS RUN CAN SHOW IS NAMED BEFORE IT CAN APPEAR.
# Anticipatory, NOT measured on this machine (which had already granted
# Terminal everything): Apple's App Management (TCC, macOS 13+) documents
# that modifying app bundles can prompt "Terminal would like to manage
# apps". The person this file is written for was promised no password and
# no surprises; an unexplained system dialog mid-run reads as "something
# went wrong". A denial is handled below (the icon falls back to the home
# folder).
# On every system-folder write, not only the first: App Management is
# documented for MODIFYING an installed bundle, so the replace case is
# the one MOST likely to raise the dialog, and the earlier
# first-write-only gate silenced the sentence exactly there. One line of
# transcript per update is the cost; an unexplained system dialog is the
# alternative.
if [ "$APP_SKIP_ICON" != "yes" ] && [ -z "${KOSMOS_APP_DIR:-}" ] && [ "$APP_DIR" = "$SYS_APP_DIR" ]; then
  info "if your Mac asks whether Terminal can manage apps, that is this step; Allow puts the icon in Applications"
fi
APP_MADE=no
if [ "$APP_SKIP_ICON" = "yes" ]; then
  : # said below, where the not-made sentences live
elif ! mkdir -p "$APP_DIR" 2>/dev/null; then
  # NON-fatal, like every other icon failure in this step: an unwritable
  # or file-shadowed Applications folder must not abort a run that can
  # still deliver a working Kosmos. The give-up sentence below covers it.
  :
# (Under the verbatim KOSMOS_APP_DIR override this gate is skipped by
# design; a foreign occupant there still cannot be destroyed, because
# make_app re-verifies ownership contemporaneously and fails into the
# generic give-up sentence instead of the specific left-alone one.)
elif [ -z "${KOSMOS_APP_DIR:-}" ] && [ "$APP_DIR" != "$SYS_APP_DIR" ] \
     && { [ -e "$APP_DIR/Kosmos.app" ] || [ -L "$APP_DIR/Kosmos.app" ]; } \
     && ! bundle_is_ours "$APP_DIR/Kosmos.app"; then
  # ⚠️ THE HOME FOLDER GETS THE SAME OWNERSHIP GATE AS EVERY OTHER
  # destructive site. This was the one path left that replaced an
  # occupant without proof -- while the uninstall sweep and the stale
  # cleanup on the SAME directory both refuse without it -- and make_app
  # renames the occupant aside and deletes it. A stranger's app named
  # Kosmos.app in the user's own folder is theirs; no icon is written,
  # and the sentence below says so.
  APP_HOME_FOREIGN=yes
elif make_app "$APP_DIR/Kosmos.app"; then
  APP_MADE=yes
elif [ -z "${KOSMOS_APP_DIR:-}" ] && [ "$APP_DIR" = "$SYS_APP_DIR" ]; then
  # ⚠️ A WRITABLE FOLDER IS NOT A CREATABLE BUNDLE. The mkdir probe proves
  # POSIX write on the directory; a root-owned leftover Kosmos.app or a
  # TCC App Management denial can still fail the bundle write inside it.
  # Before 2026-08-13 the icon reliably landed in ~/Applications, so
  # ending with NO icon anywhere would be strictly worse than the
  # discoverability bug this branch fixes. One retry into the per-user
  # folder before giving up -- guarded by the same aliasing test as the
  # divert, because "retry in the home folder" is only a retry when the
  # home folder is a different folder.
  _retry_ok=no
  if [ ! -e "$HOME_APP_DIR" ] && [ ! -L "$HOME_APP_DIR" ]; then
    _retry_ok=yes
  else
    _home_apps_phys="$(cd "$HOME_APP_DIR" 2>/dev/null && pwd -P)" || _home_apps_phys=""
    _sys_apps_phys="$(cd "$SYS_APP_DIR" 2>/dev/null && pwd -P)" || _sys_apps_phys=""
    if [ -n "$_home_apps_phys" ] && [ -n "$_sys_apps_phys" ] && [ "$_home_apps_phys" != "$_sys_apps_phys" ]; then
      _retry_ok=yes
    fi
  fi
  # The system-folder outcome is recorded BEFORE the retry can branch
  # away (including the aliased _retry_ok=no leg): the transcript
  # otherwise went quiet about Applications entirely on those legs,
  # right after the TCC warm-up set the expectation that an icon would
  # land there. The reason is "swap", not "probe": this account could
  # write the folder.
  if [ -e "$SYS_APP_DIR/Kosmos.app" ] || [ -L "$SYS_APP_DIR/Kosmos.app" ]; then
    APP_SYS_STALE=swap
  else
    APP_SYS_FAILED=yes
  fi
  if [ "$_retry_ok" = "yes" ]; then
    APP_DIR="$HOME_APP_DIR"
    # The same home-folder ownership gate as the direct path above: the
    # retry must not replace an occupant it cannot prove is ours either.
    if { [ -e "$APP_DIR/Kosmos.app" ] || [ -L "$APP_DIR/Kosmos.app" ]; } \
       && ! bundle_is_ours "$APP_DIR/Kosmos.app"; then
      APP_HOME_FOREIGN=yes
    elif mkdir -p "$APP_DIR" 2>/dev/null && make_app "$APP_DIR/Kosmos.app"; then
      APP_MADE=yes
    fi
  fi
fi
if [ "$APP_MADE" = "yes" ]; then
  # The sentence names where the icon ACTUALLY went. "you will find it in
  # Applications" was printed on the run that put it in ~/Applications, and
  # the tester could not find it -- a true sentence read as a false one.
  if [ "$APP_DIR" = "$SYS_APP_DIR" ]; then
    info "you will find it in Applications, as Kosmos"
    # An earlier install may have left the icon in ~/Applications (the only
    # place this script wrote before 2026-08-13). Once the icon lives in
    # the system folder, the old one is a second, staler Kosmos in the
    # place nobody looks -- removed, bounded by the fixed leaf name, and
    # the MOVE IS NAMED: a person whose Dock pointed at the old bundle now
    # holds a dead Dock icon, and a silent move is how that reads as "the
    # product broke". Never under the verbatim override (a KOSMOS_APP_DIR
    # sandbox must not reach into the home folder at all).
    #
    # ⚠️ AND ONLY WHEN THE TWO FOLDERS ARE PHYSICALLY DIFFERENT. `-d` follows
    # symlinks: on a machine where ~/Applications is a symlink to
    # /Applications (or the harness points SYS_APP_DIR into the home
    # folder), the "stale icon" IS the bundle written two lines up, and
    # this cleanup would delete the app it just installed while printing
    # success. Reproduced during review; the pwd -P compare is the guard.
    # ⚠️ AND NEVER WHEN THE ENTRY ITSELF IS A SYMLINK. bundle_is_ours
    # already rejects a link at the root, so without this guard nothing
    # would be deleted; but the phys compares and the left-alone note
    # below would still fire on a link to the bundle just written,
    # narrating a stale icon that does not exist. A link is not a stale
    # bundle; it is left exactly as found, silently.
    # ⚠️ COMBINED sandbox gate, not the single var (#226): every other
    # sandbox-aware line in this file treats EITHER app-dir override as "this
    # is a harness run", including the two lsregister brackets inside this very
    # block. A run sandboxed only by KOSMOS_SYS_APP_DIR would otherwise walk in
    # here and rm the REAL ~/Applications copy during a normal install step.
    # Gate: never under the verbatim override; under the system-folder override
    # ONLY when the harness has named a disposable home folder (HOME_APP_DIR).
    if [ -z "${KOSMOS_APP_DIR:-}" ] && { [ -z "${KOSMOS_SYS_APP_DIR:-}" ] || [ -n "${KOSMOS_HOME_APP_DIR:-}" ]; } && [ -d "$HOME_APP_DIR/Kosmos.app" ] && [ ! -L "$HOME_APP_DIR/Kosmos.app" ]; then
      _home_apps_phys="$(cd "$HOME_APP_DIR" 2>/dev/null && pwd -P)" || _home_apps_phys=""
      _app_dir_phys="$(cd "$APP_DIR" 2>/dev/null && pwd -P)" || _app_dir_phys=""
      if [ -n "$_home_apps_phys" ] && [ -n "$_app_dir_phys" ] && [ "$_home_apps_phys" != "$_app_dir_phys" ]; then
        # ⚠️ AND ONLY WITH PROOF OF OWNERSHIP, the same anchored token as
        # everywhere else: "the stale icon this script wrote before
        # 2026-08-13" is the only bundle this cleanup exists for, and a
        # genuine one always carries the launcher line. Anything else
        # named Kosmos.app in the user's own folder is theirs, is left
        # alone, and is named.
        if bundle_is_ours "$HOME_APP_DIR/Kosmos.app"; then
          # Unregister BEFORE the removal (lsregister searches paths for
          # applications, so -u on an already-deleted path is likely a
          # no-op and would leave the stale Spotlight record this call
          # exists to clear), and RE-register on the failure leg so a
          # bundle the note tells the user to go find is not one
          # Spotlight says does not exist. Both directions best-effort,
          # both skipped in a sandbox.
          _lsreg=/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister
          if [ -z "${KOSMOS_APP_DIR:-}${KOSMOS_SYS_APP_DIR:-}${KOSMOS_HOME_APP_DIR:-}" ]; then
            [ -f "$_lsreg" ] && [ -x "$_lsreg" ] && "$_lsreg" -u "$HOME_APP_DIR/Kosmos.app" >/dev/null 2>&1 || true
          fi
          if rm -rf "$HOME_APP_DIR/Kosmos.app" 2>/dev/null; then
            info "note: the Kosmos icon moved here from the Applications folder inside your home folder."
            info "If Kosmos was in your Dock, remove it and drag the new one in."
          else
            if [ -z "${KOSMOS_APP_DIR:-}${KOSMOS_SYS_APP_DIR:-}${KOSMOS_HOME_APP_DIR:-}" ]; then
              [ -f "$_lsreg" ] && [ -x "$_lsreg" ] && "$_lsreg" -f "$HOME_APP_DIR/Kosmos.app" >/dev/null 2>&1 || true
            fi
            info "note: an older Kosmos icon is still in the Applications folder inside your home folder; drag it to the Trash."
          fi
        else
          info "note: a Kosmos.app not created by this install is in the Applications folder inside your home folder; it was left alone."
        fi
      elif [ -z "$_home_apps_phys" ]; then
        # The fail-closed legs say so, split the same way as the
        # uninstall's guard: the note names the side that actually failed
        # the check. Only the physically-equal leg stays silent, because
        # there the "stale icon" is the bundle just written and nothing
        # is stale. (The home leg is believed unreachable -- the -d test
        # above already needs the search bit cd needs -- and is kept as
        # defense; no driving pass is possible.)
        info "note: could not check the Applications folder inside your home folder; anything there was left alone."
      elif [ -z "$_app_dir_phys" ]; then
        info "note: could not check $APP_DIR, so anything in the Applications folder inside your home folder was left alone."
      fi
    fi
  else
    if [ "$APP_OTHER_OWNER" = "yes" ]; then
      # Claims only what the failed ownership match observed: "not created
      # by this install" covers another account's Kosmos AND a third-party
      # app carrying the name, where "another account has Kosmos" would
      # assert something never established.
      info "something else already has the Kosmos spot in Applications, so yours went to the"
      info "Applications folder inside your home folder, as Kosmos (or type Kosmos into Spotlight)"
    else
      info "you will find it in the Applications folder inside your home folder, as Kosmos"
      info "(or type Kosmos into Spotlight)"
      if [ "$APP_SYS_STALE" = "probe" ]; then
        info "note: the older Kosmos icon in Applications could not be updated from this account;"
        info "use the new one (the old one may be out of date)"
      elif [ "$APP_SYS_STALE" = "swap" ]; then
        # "could not be replaced" and nothing more: this leg fires on ANY
        # make_app failure in a writable system folder (an immutable
        # bundle, a TCC denial, a failed stage), and the transcript must
        # not name a cause it never observed.
        info "note: the older Kosmos icon in Applications could not be replaced; use the"
        info "new one (the old one may be out of date)"
      elif [ "$APP_SYS_FAILED" = "yes" ]; then
        # No cause named: this leg fires on any refused write (TCC, full
        # disk, a lost race), and the transcript claims only the outcome.
        info "note: the icon could not be put into Applications this time; the one in"
        info "your home folder works the same"
      fi
    fi
  fi
  ok
elif [ "$APP_HOME_FOREIGN" = "yes" ]; then
  info "note: a Kosmos.app not created by this install is in the Applications folder inside"
  info "your home folder; it was left alone and no icon was created."
  if [ "$APP_OTHER_OWNER" = "yes" ]; then
    info "(something else also has the Kosmos spot in Applications; it was left alone too)"
  fi
  if [ "$APP_SYS_STALE" = "swap" ]; then
    info "(the Kosmos icon already in Applications could not be replaced and is still there)"
  elif [ "$APP_SYS_STALE" = "probe" ]; then
    info "(the Kosmos icon already in Applications could not be updated from this account and is still there)"
  elif [ "$APP_SYS_FAILED" = "yes" ]; then
    info "(no icon could be put into Applications this time either)"
  fi
  info "The closing lines below say how to open Kosmos."
elif [ "$APP_SKIP_ICON" = "yes" ]; then
  # The fail-closed leg of the divert's aliasing guard: something not ours
  # holds the system spot AND the home Applications folder is (or cannot be
  # proven not to be) the same physical folder, so there is nowhere an icon
  # can go without touching a stranger's app. Say so, claiming only what
  # the resolve actually observed; the dashboard address in the closing
  # lines still opens Kosmos.
  if [ "$APP_SKIP_REASON" = "same" ]; then
    info "something else already has the Kosmos spot in Applications, and this computer's home"
    info "Applications folder is the same folder, so no icon was created."
  else
    info "something else already has the Kosmos spot in Applications, and the folders"
    info "around it could not be checked, so no icon was created."
  fi
  info "The closing lines below say how to open Kosmos."
else
  info "could not create the app icon, but Kosmos itself is fine"
  if [ "$APP_SYS_STALE" != "no" ]; then
    info "(the Kosmos icon already in Applications is still there from before)"
  elif [ "$APP_OTHER_OWNER" = "yes" ]; then
    info "(something else has the Kosmos spot in Applications; it was left alone)"
  fi
fi

# ---- #2028: make a skipped/failed app-bundle write VISIBLE ------------------
# APP_MADE=no means make_app did not (re)write the bundle this run: it was
# skipped (APP_SKIP_ICON -- e.g. an aliased Applications folder), diverted
# (APP_HOME_FOREIGN), or failed. On an UPDATE that leaves the PREVIOUS bundle in
# place, which is latent until the engine requires something only a newer bundle
# supports -- exactly what board-token enforcement did (#1946/#1972): an app
# older than tokenizedBoardURL cannot authenticate, so a machine that had ever
# skipped make_app is locked out of its own board by an update it accepted.
# Before this, the skip was reported only as "no icon", which reads as cosmetic.
#
# This block is deliberately keyed on the GENERAL condition (APP_MADE != yes on
# an update), not on any one arm, so it is correct whichever arm fired -- the
# stale bundle is the defect either way and the remedy does not change (#2028).
#
# (1) A greppable marker in the LOG on EVERY run (not the terminal), recording
# the actual outcome and reason, so "which arm fired" is answerable from the log
# alone next time, without needing the affected machine (#2028's part 1). Direct
# append: $LOG exists and is written by here (the tee at ~1013). errexit-guarded.
# The `{ ...; } 2>/dev/null` groups the redirect so that a FAILED append-open
# (e.g. the logs dir gone) is itself suppressed -- a bare `printf >> "$LOG"
# 2>/dev/null` does NOT catch the shell's own redirect-open error. `|| true`
# keeps errexit from aborting the install over a diagnostic line.
{ printf '[%s] app-bundle: made=%s skip_icon=%s skip_reason=%s fresh_install=%s sys_stale=%s sys_failed=%s home_foreign=%s\n' \
  "$$" "$APP_MADE" "$APP_SKIP_ICON" "${APP_SKIP_REASON:-none}" "$FRESH_INSTALL" \
  "${APP_SYS_STALE:-no}" "${APP_SYS_FAILED:-no}" "${APP_HOME_FOREIGN:-no}" \
  >> "$LOG"; } 2>/dev/null || true
# (2) On an UPDATE that did not rewrite the bundle, route the operator to the
# reliable open path rather than a relaunch. This never ASSERTS the app is stale
# (it may not be); it routes around the possibility, and is correct on every
# not-made arm. Aligned with the standing #2023 rule: do NOT offer "relaunch the
# app" as a remedy -- it is measured-unreliable. Gated to updates (a fresh
# install has no previous bundle to be stale, and its own open already fired).
if [ "$FRESH_INSTALL" = "no" ] && [ "$APP_MADE" != "yes" ]; then
  info "note: this update did not refresh the Kosmos app itself. If the app opens to an"
  info "empty dashboard, open the Kosmos app from your Applications folder, or run: kosmos open"
fi

# ---- the permission acceptance (#46, Josh's ruling 2026-08-17) --------------
# Agents run Claude Code with permission prompts skipped; the FIRST such run
# on a machine shows Claude Code's own full-screen acceptance wall, and an
# agent stuck at it looks exactly like an agent thinking (Josh met this on a
# clean Mac: his first message sat against a wall of warning text). His
# ruling, verbatim intent: no extra click, no extra screen -- "when they're
# installing it they're giving us permission to do all of those things." So
# the install records the acceptance the wall exists to collect.
#
# ⚠️ The key is skipDangerousModePermissionPrompt in ~/.claude/settings.json.
# The fleet bulletin's trap: defaultMode alone is NOT enough; only this key
# stops the wall. MERGE, never clobber -- the file may carry a person's real
# Claude Code settings, and an installer that eats somebody's config to set
# one flag is worse than the wall. The merge runs on the Node runtime THIS
# INSTALL just verified runnable -- /usr/bin/python3 is a Command Line Tools
# shim, and its first invocation on a clean Mac can pop Apple's developer-
# tools dialog mid-install, the exact machine this block exists for. If the
# file exists but cannot be parsed as JSON (or is not an object), LEAVE IT
# ALONE and say so (fail-soft: the wall appearing later is recoverable; a
# clobbered config is not) -- one Enter in the agent's session clears it,
# per docs/clean-machine-retest.md. The symlink, mode, and zero-byte edges
# are each pinned by tools/test-permission-acceptance.sh.
_claude_settings="$HOME/.claude/settings.json"
if "$KOSMOS_HOME/runtime/bin/node" - "$_claude_settings" <<'NODEEOF' 2>/dev/null
const fs = require('fs');
const p = require('path');
// realpath FIRST: the file may be a symlink into a dotfiles repo, and a
// rename over the link would sever it, stranding the dotfiles copy while
// the setting stops tracking. Writing through preserves the arrangement.
let target = process.argv[2];
try {
  target = fs.realpathSync(target);
} catch {
  // Absent is the clean case -- unless the PATH ITSELF is a dangling
  // symlink: renaming over that would replace the link with a file, the
  // exact severing realpath exists to prevent. Somebody's arrangement;
  // leave it and let the wall be the recoverable outcome.
  try { if (fs.lstatSync(target).isSymbolicLink()) process.exit(1); } catch { /* truly absent */ }
}
let data = {};
let prevMode = null;                     // any existing file's mode survives,
                                         // zero-byte included: empty carries
                                         // nobody's settings but the chmod was
                                         // still somebody's hand
try {
  const st = fs.statSync(target);
  prevMode = st.mode & 0o7777;
  if (st.size > 0) {
    data = JSON.parse(fs.readFileSync(target, 'utf8'));   // throws -> refusal
    if (!data || typeof data !== 'object' || Array.isArray(data)) process.exit(1);
  }
} catch (err) {
  if (err && err.code === 'ENOENT') { /* absent is the clean case */ }
  else if (err instanceof SyntaxError) process.exit(1);   // somebody's file, leave it
  else process.exit(1);
}
if (data.skipDangerousModePermissionPrompt === true) process.exit(0);
data.skipDangerousModePermissionPrompt = true;
fs.mkdirSync(p.dirname(target), { recursive: true });
const tmp = target + '.kosmos.new';
// Born at the preserved mode, not chmodded into it: a tightened file's
// merged contents must never sit world-readable even for the window
// between write and chmod (the chmod after still runs for umask
// exactness).
fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', prevMode !== null ? { mode: prevMode } : {});
if (prevMode !== null) {
  // The person may have tightened their settings file; a replace must not
  // silently widen it back to the umask default.
  fs.chmodSync(tmp, prevMode);
}
fs.renameSync(tmp, target);
NODEEOF
then
  info "agents will not stop to ask permission for each action; installing is that permission"
  info "(this answers Claude Code's one-time skip-permissions question for this whole Mac,"
  info "so anything else using that mode will not ask either)"
else
  info "could not record the agent permission setting; the first agent may show a"
  info "one-time question in its own window, and answering it once clears it for good"
fi

# ---- the reporting hooks (#561) ---------------------------------------------
# Layer 1 of the report interface: Claude Code hooks that run `kosmos report`
# so the board reads each agent's state from the agent's own record instead
# of scraping its pane (#526 shipped the verb; this gives it a mouth on every
# machine). ONE merge implementation does all the wiring -- engine/reporthook
# -- called here for the default ~/.claude and every existing account dir,
# and by accounts.prepare for every account born later. Updates re-run this
# script, so machines that predate the hook pick it up on their next update.
# Same fail-soft posture as the permission block above: a machine that could
# not be wired still installs, and the board falls back to reading screens,
# which is the pre-hook world rather than a corruption.
# ⚠️ The heredoc marker here must NOT be the one the permission block above
# uses, and this comment must not spell that marker either: the permission
# acceptance test extracts the merge program above by sed-slicing this file
# from any line matching that marker's opener shape to the next line that is
# exactly the marker -- so a second heredoc using it (the first version of
# this block), or even a comment containing the opener text (the second
# version), concatenates into its fixture and fails the suite.
if "$KOSMOS_HOME/runtime/bin/node" - "$KOSMOS_HOME" <<'HOOKSEOF' 2>/dev/null
const path = require('path');
const kosmosHome = process.argv[2];
const reporthook = require(path.join(kosmosHome, 'app', 'engine', 'reporthook.js'));
const accounts = require(path.join(kosmosHome, 'app', 'engine', 'accounts.js'));
const script = reporthook.hookScriptPath();
/* ⚠️ ONE HOME FOR BOTH HALVES of this loop: accounts.list() scans the HOME
   accounts resolved (AGENT_WORKFORCE_HOME first, for sandboxing), so the
   default ~/.claude target must resolve through THE SAME answer -- reading
   process.env.HOME here would wire the operator's real settings while
   iterating a sandbox's accounts, two roots in one loop. (Angel's review.) */
const home = accounts.HOME_FOR_TEST;
const targets = [path.join(home, '.claude', 'settings.json')]
  .concat(accounts.list().filter((a) => !a.isDefault).map((a) => path.join(a.dir, 'settings.json')));
let refused = 0;
for (const t of targets) {
  const got = reporthook.ensureWired(t, script);
  if (got.wired !== true) refused += 1;
}
/* #3946: the same targets get the statusline that records the account's weekly
   usage (engine/allowance.js). It is NOT counted in `refused`: an account that
   already has its own statusline is left alone on purpose, which is expected,
   not a failure of the hooks this block reports on. Guarded so a problem here
   can never change the hooks' answer. */
try {
  const allowance = require(path.join(kosmosHome, 'app', 'engine', 'allowance.js'));
  for (const t of targets) { try { allowance.ensureStatusLine(t); } catch { /* fail soft */ } }
} catch { /* missing from this bundle, or it failed to load: the hooks' answer stands */ }
process.exit(refused === 0 ? 0 : 1);
HOOKSEOF
then
  info "agents on this computer report what they are doing themselves; the board reads their"
  info "own words instead of their screens"
else
  info "some agent settings could not carry the reporting hook (an unreadable settings"
  info "file is left alone on purpose); those agents stay readable the older way"
fi
# #3946: said only when a settings file this block targets now carries our status
# line (checked by its marker, the same way uninstall names it), so a machine where
# it could not be wired is not told that it was.
_sl_home="${AGENT_WORKFORCE_HOME:-$HOME}"
_sl_added=""
for _sl in "$_sl_home/.claude/settings.json" "$_sl_home"/.claude-*/settings.json; do
  [ -f "$_sl" ] && grep -q 'kosmos-statusline\.js' "$_sl" 2>/dev/null && _sl_added=yes
done
if [ -n "$_sl_added" ]; then
  info "Claude accounts that had no status line of their own carry Kosmos's, in every"
  info "Claude session on them: it notes how much of the weekly allowance is used and"
  info "prints nothing, which leaves an empty row under the prompt"
fi

# ---- start ------------------------------------------------------------------
# 🔑 DERIVED HERE, BEFORE THE BOARD FIRST STARTS, NOT JUST WRITTEN INTO THE
# LOGIN-JOB PLIST BELOW (#883). `kosmos start` on the next line is a plain
# child of THIS shell -- it inherits whatever is `export`ed right here, not
# what a launchd job's EnvironmentVariables carries (that only applies to a
# FUTURE reboot or self-update run). Deriving these only at the "Keeping
# Kosmos running" step further down left THIS SAME session's board starting
# with the caller's original (still machine-global) environment -- and once
# `engine/create.js`'s own #634 guard existed to catch a half-sandboxed
# mix (AGENT_WORKFORCE_LAUNCH set, the other three not), that combination is
# exactly what a naive install-time-only derivation produces when
# AGENT_WORKFORCE_LAUNCH happens to be set for file-write safety but the
# store/projects/workers roots are not yet derived -- the board refused to
# start at all. Measured while testing this fix, not assumed.
# Same non-default-KOSMOS_HOME gate as the label below; an explicit override
# from the caller always wins, matching every other ${VAR:-default} in this
# file. `_kosmos_home_default` is computed once here and reused at "Keeping
# Kosmos running" so the two steps can never disagree about which case they
# are in. Slash-normalized the SAME WAY $KOSMOS_HOME itself already was a
# few lines up top, or a $HOME carrying a trailing/doubled slash would make
# a genuinely-default install compare as non-default -- the exact bug this
# file's own header already measured once for a different comparison.
_kosmos_home_default="$(printf '%s' "$HOME/.local/share/kosmos" | /usr/bin/tr -s '/')"
_kosmos_home_default="${_kosmos_home_default%/}"
if [ "$KOSMOS_HOME" != "$_kosmos_home_default" ]; then
  [ -n "${AGENT_WORKFORCE_DATA:-}" ] || export AGENT_WORKFORCE_DATA="$KOSMOS_HOME/data"
  [ -n "${AGENT_WORKFORCE_PROJECTS:-}" ] || export AGENT_WORKFORCE_PROJECTS="$KOSMOS_HOME/projects"
  [ -n "${AGENT_WORKFORCE_WORKERS:-}" ] || export AGENT_WORKFORCE_WORKERS="$KOSMOS_HOME/workers"
  # 🛑 WITHOUT THIS, THE BOARD REFUSES TO START AT ALL (#883, caught in
  # challenge-loop, not assumed). `engine/sandbox.js`'s `audit()` (#634) is
  # symmetric: ANY of {DATA, PROJECTS, WORKERS, LAUNCH} sandboxed while ANY
  # stays live -- in EITHER direction -- is "half-sandboxed" and refused.
  # This card deliberately does not touch AGENT_WORKFORCE_LAUNCH (moving
  # agent-job plists off the one directory macOS actually auto-scans at
  # login is a real, separate change, see the plan's "deliberately not
  # touched" section) or tmux (Pete's walk needs a genuinely working board,
  # so making tmux inert would defeat the point). So the three lines above,
  # by themselves, derive exactly 3 of the 4 knobs #634 checks, leaving
  # AGENT_WORKFORCE_LAUNCH and tmux live -- which #634 was built to refuse.
  # `AGENT_WORKFORCE_HALF_SANDBOX_OK=1` is that file's own named escape
  # hatch, "for the person who has read this and means it" -- and a
  # non-default KOSMOS_HOME choosing to derive these three IS exactly that
  # person, deliberately, not by accident. This does not reopen #634's
  # original incident: that incident was AGENT_WORKFORCE_WORKERS staying
  # live while DATA/PROJECTS were sandboxed, which corrupted real agents'
  # CLAUDE.md files over real tmux sends -- WORKERS is one of the three
  # derived here, so that exact exposure stays closed. What remains open
  # (an agent job or tmux session created under this KOSMOS_HOME could
  # collide by NAME with a real one) is the same class of gap #910 and the
  # deferred agent-job-label work already name, not something this line
  # newly creates. An explicit caller override still wins, same as the
  # three lines above.
  [ -n "${AGENT_WORKFORCE_HALF_SANDBOX_OK:-}" ] || export AGENT_WORKFORCE_HALF_SANDBOX_OK=1
fi

# #2066: record which channel pointer this install fetched from, so the board can paint a
# STAGING badge for a staging tester (the read side shipped dormant in #2089: server.js
# recordedSourceChannel reads <store.ROOT>/source-channel, trims+lowercases, and folds
# anything but "staging" to prod). Written BEFORE the board starts so its first read is
# correct; a missing file reads prod, so an unrecorded staging install would masquerade as
# prod.
# #2934: this file is what the board READS, but it is no longer the whole answer. A promote
# moves no bytes, so nothing re-runs this write and the stamp goes stale; sourceChannelNow
# now takes this value and, only when it says staging, may downgrade it to prod on positive
# evidence that prod publishes the running version. This write is unchanged and still the
# only thing that sets the stamp.
#
# 🔑 ONE WRITE COVERS BOTH the fresh-install and the update path. The join contract (#2066)
# asked for a write in setup.sh AND engine/update.js, but update.js's auto-update does NOT
# install in-process: it spawns THIS setup.sh via `curl | sh` with KOSMOS_UPDATE_CHANNEL set
# (engine/update.js beginInstall), so _PTR_FILE here already reflects the update's channel.
# setup.sh is the single funnel both paths share; a second write in update.js would be
# redundant and could diverge. (Flagged to Mona Lisa, the read-side author.)
#
# store.ROOT mirrors engine/store.js dataRootFor (via its root() caller, store.js:158) for
# this macOS-only installer: an AGENT_WORKFORCE_DATA override (the sandbox the tests seed),
# else AGENT_WORKFORCE_HOME (the general engine home seam, #1780), else $HOME. The
# AGENT_WORKFORCE_HOME arm is load-bearing: root() reads AGENT_WORKFORCE_HOME||os.homedir(),
# so a bare $HOME here would write under a different root than the board reads when that seam
# is set (DATA unset), and the badge would silently never light.
# #2439: the store leaf is 'Kosmos' now (engine/store.js APP), migrated from the
# legacy 'AgentWorkforce' leaf by maybeMigrateLegacyStore() at the top of store.root()
# on the board's first access. 🛑 THIS WRITE RUNS BEFORE `kosmos start`, so a naive
# mkdir of the NEW leaf here would create it before the board migrates -- and the
# migration NEVER CLOBBERS an existing new root (store.js:221), so the person's OLD
# AgentWorkforce data (agents, profiles, chats) would be orphaned, unread, on every
# update. So write to the CURRENT root: the legacy leaf when it exists and the new one
# does not (the pre-migration update case), else the new leaf. The board's migration
# then renames legacy -> new with this source-channel file inside it, and reads it
# correctly. Fresh install (neither leaf yet) writes straight to the new leaf.
if [ -n "${AGENT_WORKFORCE_DATA:-}" ]; then
  _wf_base="$AGENT_WORKFORCE_DATA"
else
  _wf_base="${AGENT_WORKFORCE_HOME:-$HOME}/Library/Application Support"
fi
if [ -d "$_wf_base/AgentWorkforce" ] && [ ! -d "$_wf_base/Kosmos" ]; then
  _wf_data_root="$_wf_base/AgentWorkforce"
else
  _wf_data_root="$_wf_base/Kosmos"
fi
if [ "$_PTR_FILE" = "latest-staging.json" ]; then _source_channel=staging; else _source_channel=prod; fi
# #2969: the updater names the SUBSCRIPTION separately from the pointer it installs from. A
# staging subscriber offered a newer PROD build (a prod-only hotfix cut) installs from latest.json
# but must stay subscribed to staging, or the next staging build would never reach it. Only the two
# known values are honoured; anything else keeps the pointer-derived stamp above.
case "${KOSMOS_SOURCE_CHANNEL:-}" in staging|prod) _source_channel="$KOSMOS_SOURCE_CHANNEL" ;; esac
if mkdir -p "$_wf_data_root" 2>/dev/null; then
  printf '%s\n' "$_source_channel" > "$_wf_data_root/source-channel" 2>/dev/null \
    || printf '  (could not record the source channel; the board will read the default, prod)\n'
fi

# #4356: a computer can connect to agents on another computer instead of running its own. The Mac
# app records that in $KOSMOS_HOME/mode (one word: run, connect, or both, which runs agents AND
# connects to other computers) and stops the board for connect, and an install or update must not
# start it again. So the board is started only when the file is absent (never chosen: a fresh
# install, and every install before #4356) or reads exactly `run` or `both`. Anything else,
# including a file that cannot be read, is not started: the installer cannot ask, and the app
# starts the board and asks again at its next launch. `$(cat ...)` drops trailing newlines, as the
# app's reader does.
# #4356 migration: an install from before the first screen has no mode file, which the app reads
# as "not chosen" and would ask about, for instance when a second Kosmos (#1852) opens its own first
# run on a Mac that has run agents for months. An update of an install whose first run is done
# records `run`, which is what that Mac has always been. A fresh install, or one whose first run
# never finished, keeps no file and is asked (review round 21).
if [ "$FRESH_INSTALL" = no ] && [ ! -e "$KOSMOS_HOME/mode" ] && [ -f "$_wf_data_root/first-run.json" ]; then
  # Atomic (a temp file, then a rename), as the app writes it, so the app never reads half a word.
  # A temp left by an earlier run killed mid-write goes first (its pid is gone, so only a glob finds it).
  rm -f "$KOSMOS_HOME"/mode.new.* 2>/dev/null || true
  { printf 'run\n' > "$KOSMOS_HOME/mode.new.$$" && mv -f "$KOSMOS_HOME/mode.new.$$" "$KOSMOS_HOME/mode"; } 2>/dev/null \
    || rm -f "$KOSMOS_HOME/mode.new.$$" 2>/dev/null || true
fi
# Read again now (_kosmos_board_decide): the person may have answered the first screen, or used the
# menu, during this run. The latest reading decides whether this run starts the board.
_kosmos_board_decide
_kosmos_started=no; _kosmos_wrote_marker=no
if [ "$_kosmos_board_off" = yes ]; then
  _kosmos_wrote_marker=yes
  # The marker is what launchd's login item (board-run) and the watchdog obey. An update's pause
  # already wrote it; a run that did not pause (a fresh bin/ over a leftover home) has not, and
  # without it the login item bootstrapped below would start the board this run just declined to.
  : > "$KOSMOS_HOME/board.stopped" 2>/dev/null || true
  if [ "$_kosmos_mode_word" = connect ]; then
    step "This computer connects to agents on another computer, so Kosmos is not started here."
  else
    step "This computer's setup choice could not be read, so Kosmos is not started here. The Kosmos app will ask again when you open it."
  fi
else
  step "Starting Kosmos."
  _kosmos_started=yes
  # #4466: KOSMOS_RECLAIM_BUSY=1 because at this point no board of this install should be serving (an update
  # has just stopped the old one; a fresh install never had one), so a Kosmos that holds the port without
  # answering is a stale build, not a busy one (the #3079 reclaim frees it, as it did before #4466).
  KOSMOS_SAY_INDENT="     " KOSMOS_RECLAIM_BUSY=1 "$KOSMOS_HOME/bin/kosmos" start --force || die "Kosmos installed but would not start. What it said is above; it is safe to paste the install line again."
  _kosmos_paused_board=no   # #4818: the new board started, so a later failure restarts nothing
fi
ok

# ---- and start it again at every login --------------------------------------
#
# 🛑 THE BOARD WAS THE ONE PIECE WITH NO LOGIN JOB, and every agent had one.
# `kosmos start` runs the server under `nohup`, which survives the terminal that
# launched it and nothing else: a reboot ends it, and NOTHING anywhere started
# it again. Measured on Josh's machine on 2026-08-22, and the reason it read as
# total failure rather than as one dead process is that the browser still had
# the page cached — so every panel rendered and every panel said "we could not
# check this computer". The product looked broken in six places at once because
# the one thing that answers questions was not running.
#
# ⚠️ THIS FLEET'S OWN MAC HAD A HAND-WRITTEN com.kosmos.board.plist since
# 10 August, so the dev board came back after every reboot and a real install
# never did. We were configured out of our own bug, which is why nobody hit it
# for eleven days. Two things that file learned the hard way are carried into
# the template below rather than rediscovered: launchd sets neither PATH nor
# LANG, and without LANG tmux sanitises its format output so every agent comes
# back named `angel-discord_0.0_2.1.223_…` with the tab separators replaced.
#
# ⚠️ RunAtLoad AND a KeepAlive keyed on the deliberate-stop marker (#2956). This
# used to be RunAtLoad with NO KeepAlive, deliberately, because the old
# ProgramArguments ran `kosmos start`, which daemonised and exited: a plain
# KeepAlive would have relaunched that the instant it returned (a loop), and
# launchd owning the detached node directly broke `kosmos stop`. #2956 resolves
# both: ProgramArguments now runs `kosmos board-run`, which grew a FOREGROUND mode
# (it execs node in place), so launchd owns the actual board process and its
# KeepAlive supervises a crash. `kosmos stop` still means stopped because the
# KeepAlive is PathState-keyed on the board.stopped marker (present -> launchd
# leaves it down; absent -> supervised), not on exit status -- so a SIGTERM stop
# is honored, and the updater's stop/swap/start rides the same marker. The #2955
# watchdog stays one release as belt-and-braces for boards not yet rebooted onto
# this plist (an update rewrites the file but does not reload a loaded job until
# the next login).
# #4356: the heading says what this run does. On a computer set not to run a board, the login item is
# still installed (so "Run agents on this computer" works later) and board.stopped keeps it off.
if [ "$_kosmos_board_off" = yes ]; then
  step "Preparing Kosmos to start at login. It stays off $(_kosmos_off_why)."
else
  step "Keeping Kosmos running after a restart."
fi
_launch_dir="${AGENT_WORKFORCE_LAUNCH:-$HOME/Library/LaunchAgents}"
# ⚠️ THE LABEL IS UNIQUE ONLY WHEN KOSMOS_HOME IS NOT THE REAL DEFAULT (#883).
# A default install's label MUST stay the literal `com.kosmos.board` --
# EVERY existing real user's board is already registered under that exact
# string, and this same script runs again on every self-update
# (engine/update.js spawns the installer), so relabeling a default install
# would orphan every real user's login job on their next reboot. That is a
# strictly worse regression than the collision this guards against. Pinned
# by a dedicated test that the default-KOSMOS_HOME plist is byte-identical
# to before this change.
# A sandboxed/walk install (KOSMOS_HOME pointed at a scratch dir) is where
# the collision actually happened: Pete's release-walk convention sets only
# KOSMOS_HOME + KOSMOS_HOME_APP_DIR + KOSMOS_PORT, never AGENT_WORKFORCE_LAUNCH,
# so its plist file lands in the SAME real ~/Library/LaunchAgents as any real
# install -- and with the same fixed label, launchd's registry treats the
# second install's job as the first one, silently overwriting the file a
# real, hand-registered board depended on (observed live, 0.5.30/0.5.31
# walks). The suffix is a short hash of KOSMOS_HOME, not a counter or a
# timestamp, so the SAME sandboxed install re-run (a walk's own update tick)
# derives the SAME label every time -- required for the "already-loaded job
# is left alone" idempotency check a few lines below to keep meaning that,
# rather than accumulating a fresh orphaned label on every re-run.
_board_label=com.kosmos.board
if [ "$KOSMOS_HOME" != "$_kosmos_home_default" ]; then
  _board_label="com.kosmos.board.$(printf '%s' "$KOSMOS_HOME" | shasum -a 256 | cut -c1-8)"
fi
_board_plist="$_launch_dir/$_board_label.plist"
# Paths are user-controlled (KOSMOS_HOME is overridable) and this is XML, so
# they are escaped rather than trusted to be boring. Five characters, in the
# order that keeps `&` from eating the escapes it introduces.
_xmlq() { printf '%s' "$1" | sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s/"/\&quot;/g'; }
# ⚠️ THE STORE, PROJECTS FOLDER, AND WORKERS FOLDER ARE NOT SANDBOXED EITHER
# (#883, escalated by Josh past the label alone: a sandboxed board and the
# real board on one machine share ONE store -- projects.json records,
# avatars, chats, selfreports, all real data a real user meets). Persisted
# here into the login job so a FUTURE reboot or self-update (engine/
# update.js re-runs this exact script) carries the same roots the "Starting
# Kosmos" step above already exported for THIS session -- a launchd job
# inherits only what EnvironmentVariables carries, nothing from the shell
# that wrote it. engine/create.js, engine/projects.js, and engine/store.js
# already read AGENT_WORKFORCE_WORKERS / _PROJECTS / _DATA correctly when
# present (confirmed by reading each).
# Emitted whenever KOSMOS_HOME is non-default: by this point in the script
# the three vars are ALREADY resolved one way or another (either the
# caller's own explicit override, or the derivation above) -- there is
# nothing left to conditionally check here. A default install gets none of
# these three keys at all, not merely empty ones -- same byte-identical
# invariant as the label above.
_env_kv() { # $1 = key name, $2 = value (already the final, unescaped path)
  printf '    <key>%s</key><string>%s</string>\n' "$1" "$(_xmlq "$2")"
}
# ⚠️ ONE PRE-BUILT BLOCK, NOT THREE SEPARATE LINES, so a default install's
# plist carries ZERO added bytes -- three individually-empty variables would
# each still leave their own blank/whitespace line in the heredoc, breaking
# the byte-identical invariant above for every real install even when none
# of the three keys apply. Empty string here means "nothing inserted here
# at all", not "three blank lines".
_extra_env_kv=""
if [ "$KOSMOS_HOME" != "$_kosmos_home_default" ]; then
  # ⚠️ FOUR KEYS, NOT THREE. `AGENT_WORKFORCE_HALF_SANDBOX_OK` (#883,
  # challenge-loop iteration 4, caught by a direct reproduction, not a
  # reading) is exported into THIS session above, before "Starting
  # Kosmos.", so the immediate same-session start clears #634's guard --
  # but that export dies with this script's process. The launchd job
  # written below inherits ONLY what its own EnvironmentVariables dict
  # carries; at the NEXT login or self-update, `kosmos start` runs as a
  # fresh process whose entire environment IS that dict, nothing more. The
  # first version of this fix persisted DATA/PROJECTS/WORKERS there but
  # not the override that makes them safe together -- so a real Pete-
  # convention board would start fine today and refuse to start half-
  # sandboxed at the very next reboot, the identical #634 refusal this
  # whole fix exists to clear, just deferred. Reproduced directly: invoked
  # `bin/kosmos start` with ONLY the plist's own EnvironmentVariables (no
  # override key) and watched it die with exactly that sentence.
  # ⚠️ ALL FOUR CAPTURED IN ONE COMMAND SUBSTITUTION, WITH A SENTINEL, so
  # the newline AFTER THE LAST line survives. Command substitution strips
  # EVERY trailing newline from what it captures -- calling `_env_kv`
  # four times as four SEPARATE $(...) each loses its own trailing \n
  # before the strings are even concatenated (every key/string pair lands
  # on one physical line, valid XML but not the one-key-per-line shape
  # every other entry in this dict has), and even one outer $(...) around
  # all four would still strip the LAST \n, running the HALF_SANDBOX_OK
  # line straight into the "  </dict>" this variable sits beside in the
  # heredoc below. Appending a literal `X` after the real content,
  # capturing THAT, then stripping the `X` with `${var%X}` is the standard
  # portable way to keep a command substitution's trailing newlines: the
  # `X` is not a newline, so nothing gets stripped until `%X` removes it.
  _extra_env_kv="$( { _env_kv AGENT_WORKFORCE_DATA "$AGENT_WORKFORCE_DATA"; _env_kv AGENT_WORKFORCE_PROJECTS "$AGENT_WORKFORCE_PROJECTS"; _env_kv AGENT_WORKFORCE_WORKERS "$AGENT_WORKFORCE_WORKERS"; _env_kv AGENT_WORKFORCE_HALF_SANDBOX_OK "$AGENT_WORKFORCE_HALF_SANDBOX_OK"; printf 'X'; } )"
  _extra_env_kv="${_extra_env_kv%X}"
fi
_board_ok=no
# 🛑 THIS HEREDOC IS UNQUOTED, so every $(...) and every backtick in its body
# RUNS while the plist is written. That is REQUIRED for the $(_xmlq ...) escaping
# below, but it means a backtick or a $ in a COMMENT here executes too: a comment
# containing `kosmos start` literally RAN kosmos start on every update (mid-swap,
# with kosmos on PATH) and "kosmos: command not found" on a fresh Mac (#666/#667).
# RULE: nothing in this heredoc body may use a backtick or a bare $word; the only
# expansions allowed are the intended $(_xmlq ...), $_board_label, and the
# pre-built $_extra_env_kv block -- already fully XML-escaped by _env_kv above
# (which itself only ever calls _xmlq, never prints anything raw), so a bare
# reference to it here is exactly as safe as $(_xmlq ...) inline, just built
# ahead of time because a heredoc alone cannot conditionally omit a whole line
# the way an empty _extra_env_kv can (a default install must add zero bytes,
# not blank lines, #883). Guarded by
# tools/test-plist-heredoc-clean.sh.
if mkdir -p "$_launch_dir" 2>/dev/null && cat > "$_board_plist.new" <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>$_board_label</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>$(_xmlq "$KOSMOS_HOME/bin/kosmos")</string>
    <string>board-run</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>HOME</key><string>$(_xmlq "$HOME")</string>
    <key>PATH</key><string>$(_xmlq "$KOSMOS_HOME/tmux/bin"):/usr/bin:/bin:/usr/sbin:/sbin</string>
    <key>LANG</key><string>en_US.UTF-8</string>
    <key>KOSMOS_PORT</key><string>$(_xmlq "$PORT")</string>
$_extra_env_kv  </dict>
  <!-- Whose background item this is, so macOS files it under Kosmos in Login
       Items rather than as an anonymous entry the person cannot place. Same
       identifier the agents' jobs carry. -->
  <key>AssociatedBundleIdentifiers</key>
  <array><string>com.chaoskosmos.kosmos</string></array>
  <key>RunAtLoad</key><true/>
  <!-- #2956: launchd SUPERVISES the board. ProgramArguments runs "board-run",
       which execs node in the foreground, so this job IS the board process and a
       crash is launchd's to relaunch. KeepAlive is keyed (PathState) on the
       deliberate-stop marker (the same file "kosmos stop" writes and "kosmos
       start" clears, de-referenced here as the intended _xmlq escape, not a bare
       word -- see the heredoc warning above): the board is kept running WHILE the
       marker path is absent (false), and a deliberate stop that creates it makes
       launchd stop the job and not relaunch it. ThrottleInterval bounds a crash
       loop. This is keyed on presence/absence, not exit status, so a SIGTERM stop
       is honored where a plain KeepAlive would relaunch it. -->
  <key>KeepAlive</key>
  <dict>
    <key>PathState</key>
    <dict>
      <key>$(_xmlq "$KOSMOS_HOME/board.stopped")</key><false/>
    </dict>
  </dict>
  <key>ThrottleInterval</key><integer>10</integer>
  <!-- 🔑 THE SAME FILE THE BOARD ITSELF WRITES TO, and it was a second one.
       "kosmos start" (de-backticked on purpose, see the heredoc warning above)
       sends the server's own output to logs/board.log; this job
       captures the narration of the SCRIPT that starts it. Two destinations,
       nothing on the machine saying which, and the person debugging is the
       least likely to know: Josh tailed board.log on 2026-08-22 looking for the
       reason his board could not read his agents, found six startup lines and
       no error, and reasonably read that as "it is not logging anything".
       ⚠️ Both append, so one file carries the start and what the start did, in
       order. That ordering is the thing a second file destroys. -->
  <key>StandardOutPath</key><string>$(_xmlq "$KOSMOS_HOME/logs/board.log")</string>
  <key>StandardErrorPath</key><string>$(_xmlq "$KOSMOS_HOME/logs/board.log")</string>
</dict>
</plist>
PLIST
then
  mv -f "$_board_plist.new" "$_board_plist" 2>/dev/null && _board_ok=yes
fi
rm -f "$_board_plist.new" 2>/dev/null || true
if [ "$_board_ok" = yes ]; then
  # ⚠️ NO launchctl UNDER A SANDBOX. AGENT_WORKFORCE_LAUNCH set means a harness
  # pointed the plist directory at a temp folder — and launchd has no such
  # directory to point: a bootstrap here would register a REAL job on the
  # machine running the test, which outlives the test and starts a board at
  # every login from a tree the harness deleted.
  if [ -z "${AGENT_WORKFORCE_LAUNCH:-}" ]; then
    _uid="$(/usr/bin/id -u)"
    # 🛑 AN ALREADY-LOADED JOB IS LEFT ALONE, AND THE FIRST VERSION OF THIS
    # BOOTED IT OUT FIRST. That is a real hazard rather than churn, and it is in
    # code that shipped an hour before this comment.
    #
    # An update is run BY THE BOARD: `engine/update.js` spawns the installer as
    # a detached child of the running server. Once the board is a launchd job,
    # `bootout` terminates that job — the board, and every process launchd
    # associates with it — while this script is a descendant of it. The child is
    # `setsid`-ed, so it very likely survives; "very likely" is not a property
    # to rest an update path on, and the failure mode is the worst kind: the
    # bootout lands, the shell dies before `bootstrap` runs, and the machine is
    # left with the job booted out and no board at all until the next login.
    #
    # 🔑 AND NOTHING IS LOST BY SKIPPING IT. The plist on disk is already
    # rewritten above; a loaded job keeps its old definition only until the next
    # login, and this file's content does not change between versions. Reloading
    # it buys a definition refresh nobody needs, at the cost of killing the
    # board that is running the update.
    #
    # ⚠️ `print` IS THE PROBE, not `list`: it is the one `engine/create.js`
    # already uses to ask whether a label is loaded, and it fails for every free
    # name by design.
    # 🛑 NEVER FROM A SANDBOX. This bootstraps $_board_plist into the REAL
    # gui domain, and under AGENT_WORKFORCE_LAUNCH that file lives in a temp
    # dir -- so a suite run landing here while the real label happened to be
    # absent registered a TEMP-PATHED job over the product's own, and when
    # the sandbox was deleted the real board was left unsupervised. Found
    # live on the fleet Mac, 2026-08-23: com.kosmos.board pointing into
    # T/kosmos-clean-*/. The plist WRITE above stays sandboxed and asserted
    # by the suite; the launchd registration is real-machine-only.
    if [ -n "${AGENT_WORKFORCE_LAUNCH:-}" ]; then
      _board_ok=sandbox # unreachable inside the -z arm above; the belt the gate scan reads (its window is 12 lines above each launchctl call: keep this arm close)
    elif /bin/launchctl print "gui/$_uid/$_board_label" >/dev/null 2>&1; then
      : # already registered; the rewritten file is picked up at the next login
    else
      # enable BEFORE bootstrap, the order the uninstall path above documents: a
      # `launchctl disable` from any earlier life writes a per-user override
      # keyed on the label that outlives the plist, and bootstrapping into a
      # standing disable is refused (measured on macOS 26.7, #4254).
      /bin/launchctl enable "gui/$_uid/$_board_label" 2>/dev/null || true
      # Outcome CHECKED (a refused bootstrap printed success on Josh's
      # machine, 2026-08-24): not fatal, but a different true sentence.
      if ! /bin/launchctl bootstrap "gui/$_uid" "$_board_plist" 2>/dev/null; then
        _board_ok=later
      else
        # #2956: the job now runs `board-run`, and bootstrap RunAtLoad-starts it
        # immediately -- but the "Starting Kosmos" step above already brought up a
        # board with `kosmos start` (nohup, since no job was loaded then), so
        # board-run cannot bind the port and would be relaunched on a throttle
        # (board-run's own guard keeps that harmless, but it churns until reboot).
        # Reconcile to ONE launchd-supervised board now: `kosmos restart` retires the
        # nohup board and starts the supervised one (start detects the loaded
        # board-run job and kickstarts it). Best-effort: if anything here fails, the
        # board-run guard still prevents a double-bind, so this only ever improves on
        # the churn, never worsens it. (Bootstrap RunAtLoad is real launchd, skipped
        # under the sandbox above, so this path is verified on a real box, not here.)
        # #4356: not on a computer that connects elsewhere; restart would clear board.stopped.
        # (read again first: a choice made since the start step decides)
        _kosmos_board_decide
        [ "$_kosmos_board_off" = yes ] || "$KOSMOS_HOME/bin/kosmos" restart --force >/dev/null 2>&1 || true
      fi
    fi
  else
    # The file is the deliverable; the domain is not ours. Said in its own
    # sentence below (#513): a transcript narrating a registration it
    # skipped cannot be used as evidence of anything, and this guard was
    # earned twice, so its transcript must be able to PROVE it held.
    _board_ok=sandbox
  fi
  if [ "$_board_ok" = sandbox ]; then
    info "sandboxed run: the login job file was written; registering it with launchd was skipped on purpose (the real machine's domain is not this run's to touch)"
  elif [ "$_board_ok" = later ]; then
    info "note: macOS did not accept the background item just now; it is written and loads at your next login"
  elif [ "$_kosmos_board_off" = yes ]; then
    # #4356: the job is installed so "Run agents on this computer" works later, but board.stopped
    # keeps it from starting anything while the board is off on purpose.
    info "Kosmos will not start itself at login $(_kosmos_off_why)"
  else
    info "Kosmos will start itself when you log in"
  fi
  ok
else
  # ⚠️ NOT FATAL, and said in terms of what it costs rather than what failed.
  # Everything else about this install works; the person loses exactly one
  # thing, and the thing they would do instead is the thing they already do.
  info "note: could not write $_board_plist, so Kosmos will not start itself after a restart."
  [ "$_kosmos_mode_word" = connect ] || info "Opening the Kosmos icon starts it, as it always has."
fi

# #2955: THE BOARD WATCHDOG login job.
# ⚠️ #2956 UPDATE: the board plist above is NO LONGER RunAtLoad-with-no-KeepAlive.
# It now runs `kosmos board-run` (a foreground mode) under a KeepAlive keyed on the
# stop-marker, so launchd itself supervises and relaunches the board process -- the
# done-right follow-up this comment used to defer. So on a machine rebooted onto
# the new plist, launchd KeepAlive AND this watchdog both cover a crash (redundant,
# but each guarded by the same STOP_MARKER, so they agree). The watchdog is kept
# for ONE release as belt-and-braces: an update rewrites the plist file but does not
# reload a loaded job until the next login, so a board that has updated-but-not-yet-
# rebooted is still the old detached shape that only the watchdog supervises. Remove
# the watchdog in a follow-up once installs have cycled through a reboot.
# The original #2955 rationale (unchanged for the not-yet-rebooted case): if the
# detached board fails to start on a reboot -- a zombie holding port 16180 after an
# unclean power-down, a not-yet-ready dependency -- or dies later, NOTHING relaunches
# it and the app is stuck on "could not refresh" (Josh hit exactly this on live
# 0.6.59). This job runs bin/board-watchdog.sh on an interval and brings the board
# back when it has died and the user did not deliberately stop it (it reads the
# STOP_MARKER `kosmos stop` writes / `kosmos start` clears). Touches neither the
# board job nor kosmos stop/start beyond that marker.
#
# Everything below MIRRORS the board plist block above: the same non-default-
# KOSMOS_HOME hash suffix, the same _xmlq escaping, the same $_extra_env_kv (built
# once above), the same unquoted-heredoc rule (no backtick, no bare $word in the
# body -- guarded by tools/test-plist-heredoc-clean.sh), the same sandbox guard
# (no launchctl under AGENT_WORKFORCE_LAUNCH), enable-before-bootstrap, and
# leave-an-already-loaded-job-alone idempotency.
if [ "$_kosmos_board_off" = yes ]; then
  step "Setting up the helper that restarts Kosmos if it stops. It stays off $(_kosmos_off_why)."
else
  step "Watching the board so it comes back after a restart."
fi
_wd_label=com.kosmos.board.watchdog
if [ "$KOSMOS_HOME" != "$_kosmos_home_default" ]; then
  _wd_label="com.kosmos.board.watchdog.$(printf '%s' "$KOSMOS_HOME" | shasum -a 256 | cut -c1-8)"
fi
_wd_plist="$_launch_dir/$_wd_label.plist"
_wd_ok=no
# 🛑 SAME UNQUOTED-HEREDOC RULE as the board plist: nothing in this body may use a
# backtick or a bare $word; the only expansions allowed are $(_xmlq ...),
# $_wd_label, and the pre-built, already-XML-escaped $_extra_env_kv.
if mkdir -p "$_launch_dir" 2>/dev/null && cat > "$_wd_plist.new" <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>$_wd_label</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>$(_xmlq "$KOSMOS_HOME/app/bin/board-watchdog.sh")</string>
    <string>$(_xmlq "$KOSMOS_HOME")</string>
    <string>$(_xmlq "$_board_plist")</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>HOME</key><string>$(_xmlq "$HOME")</string>
    <key>PATH</key><string>$(_xmlq "$KOSMOS_HOME/tmux/bin"):/usr/bin:/bin:/usr/sbin:/sbin</string>
    <key>LANG</key><string>en_US.UTF-8</string>
    <key>KOSMOS_PORT</key><string>$(_xmlq "$PORT")</string>
$_extra_env_kv  </dict>
  <key>AssociatedBundleIdentifiers</key>
  <array><string>com.chaoskosmos.kosmos</string></array>
  <key>RunAtLoad</key><true/>
  <!-- 30s pairs with the watchdog's 45s grace: the board must be unanswering
       across at least two of these wakeups before the first restart, which covers
       a legitimate login-time start binding the port (cmd_start waits ~15s). -->
  <key>StartInterval</key><integer>30</integer>
  <key>StandardOutPath</key><string>$(_xmlq "$KOSMOS_HOME/logs/board-watchdog.log")</string>
  <key>StandardErrorPath</key><string>$(_xmlq "$KOSMOS_HOME/logs/board-watchdog.log")</string>
</dict>
</plist>
PLIST
then
  mv -f "$_wd_plist.new" "$_wd_plist" 2>/dev/null && _wd_ok=yes
fi
rm -f "$_wd_plist.new" 2>/dev/null || true
if [ "$_wd_ok" = yes ]; then
  if [ -z "${AGENT_WORKFORCE_LAUNCH:-}" ]; then
    _wd_uid="$(/usr/bin/id -u)"
    if [ -n "${AGENT_WORKFORCE_LAUNCH:-}" ]; then
      _wd_ok=sandbox # unreachable inside the -z arm above; the belt the gate scan reads (its window is 12 lines above each launchctl call: keep this arm close)
    elif /bin/launchctl print "gui/$_wd_uid/$_wd_label" >/dev/null 2>&1; then
      : # already registered; the rewritten file is picked up at the next login
    else
      # enable BEFORE bootstrap, the same order the board job uses: a stale
      # `launchctl disable` override outlives the plist and a bootstrap into a
      # standing disable is refused (measured on macOS 26.7, #4254).
      /bin/launchctl enable "gui/$_wd_uid/$_wd_label" 2>/dev/null || true
      if ! /bin/launchctl bootstrap "gui/$_wd_uid" "$_wd_plist" 2>/dev/null; then
        _wd_ok=later
      fi
    fi
  else
    _wd_ok=sandbox
  fi
  if [ "$_wd_ok" = sandbox ]; then
    info "sandboxed run: the watchdog job file was written; registering it with launchd was skipped on purpose (the real machine's domain is not this run's to touch)"
  elif [ "$_wd_ok" = later ]; then
    info "note: macOS did not accept the watchdog item just now; it is written and loads at your next login"
  elif [ "$_kosmos_board_off" != yes ]; then
    info "Kosmos will bring the board back if it stops after a restart"
  fi
  ok
else
  # Not fatal: the board still starts at login and reopening the icon still starts
  # it; the person only loses the automatic recovery this job would have added.
  info "note: could not write $_wd_plist, so Kosmos will not auto-recover the board after a restart."
fi

# ⚠️ PROVE THE BOARD ON THE PORT IS THIS INSTALL'S OWN. cmd_start's
# healthy() accepts ANY board identifying as Kosmos on the port, so on a
# Mac where another account's Kosmos already holds it, a fresh install
# "succeeds" without ever starting its own board -- and the closing
# sentences (and the app launch below) would present the OTHER
# install's board as the result of this one. Measured in review: a fresh
# install onto an occupied port printed "Kosmos is running" and opened a
# stranger's board. The pidfile cmd_start writes for a board it actually
# started is the proof; no pidfile with a live pid means the port is
# someone else's.
BOARD_OURS=no
if [ -f "$KOSMOS_HOME/board.pid" ]; then
  _bpid="$(cat "$KOSMOS_HOME/board.pid" 2>/dev/null)" || _bpid=""
  case "$_bpid" in
    ''|*[!0-9]*) ;;
    *)
      # The pid must BE the board, matched on THIS install's full server
      # path -- deliberately STRICTER than install/kosmos's running_pid,
      # which matches any *app/server.js*: a recycled pid, or another
      # install's live server behind a stale pidfile, must not read as
      # ours, because this flag gates the app launch. The harness pins
      # the anchoring with another install's live server pid; do not
      # "align" the two patterns.
      case "$(/bin/ps -ww -p "$_bpid" -o command= 2>/dev/null)" in
        *"$KOSMOS_HOME/app/server.js"*) BOARD_OURS=yes ;;
      esac
      ;;
  esac
fi

# #3058: DECIDE the auto-launch ONCE, here, BEFORE the summary, so the summary message and
# the launch block below key on the SAME signal rather than drifting. The first pass at this
# keyed the summary on APP_MADE while the launch keyed on _open_gate + bundle_is_ours, which
# disagree: a normal SEEDED UPDATE has APP_MADE=yes but _open_gate=no, so it does NOT launch,
# yet the APP_MADE summary promised "Kosmos will open"; and an APP_MADE=no run that DOES launch
# (a current bundle left in place -- see the launch header's "APP_MADE=no still has a valid app
# that must launch") printed the bare "open it yourself" imperative on a run that opened. Both
# are the exact contradiction #3058 is about. _do_open is the whole launch predicate, computed
# once and consumed by both the summary and the launch. The two knobs and the enforcing-update
# gate are documented in full at the launch site below; this is the same computation, hoisted.
# #4356: the last reading, before the summary. A computer that became connect during this run (a
# first-screen answer after the start step) has its board stopped here rather than left for the
# next login; stop writes board.stopped. An unreadable one is left as it is: the app started it to
# ask. The summary below then describes this reading.
_kosmos_board_decide
if [ "$_kosmos_mode_word" = connect ] && [ "$BOARD_OURS" = yes ]; then
  "$KOSMOS_HOME/bin/kosmos" stop --force >/dev/null 2>&1 || true
  if ! curl -s -m 2 -o /dev/null "http://127.0.0.1:$PORT/" 2>/dev/null; then BOARD_OURS=no; fi
elif [ "$_kosmos_board_off" = no ] && [ "$_kosmos_wrote_marker" = yes ]; then
  # Now run or both (the app's menu, during this run): the marker this run wrote would keep launchd
  # and the watchdog from ever bringing that board back, so it goes. The app starts the board, or
  # launchd does as soon as the marker is gone (its KeepAlive keys on it).
  rm -f "$KOSMOS_HOME/board.stopped" 2>/dev/null || true
fi
# ⚠️ KNOWN, NOT CLOSED: each reading above is followed by an action, and the app can change the file
# in between (a person using the first screen or the menu DURING an install). The window is a few
# lines wide, and the next launch of the app puts the board where the file says; a lock shared by the
# installer and the app would close it, and is not built (#4356, review round 16).

OPEN_CMD="${KOSMOS_OPEN_CMD:-/usr/bin/open}"
_awnode_r="$KOSMOS_HOME/runtime/bin/node"; _awroot_r=""; _repair_seed=""
if [ -f "$_awnode_r" ] && [ -x "$_awnode_r" ]; then
  _awroot_r="$("$_awnode_r" -e 'process.stdout.write(require(process.argv[1]).ROOT)' "$KOSMOS_HOME/app/engine/store" 2>/dev/null)" || _awroot_r=""
  [ -n "$_awroot_r" ] && _repair_seed="$_awroot_r/.reauth-seeded"
fi
_open_gate="$FRESH_INSTALL"; _opened=no
if [ -n "$_repair_seed" ] && [ ! -f "$_repair_seed" ] && [ -s "$_awroot_r/board.token" ]; then
  _open_gate=yes
fi
_do_open=no
if [ "$BOARD_OURS" = "yes" ] && [ "$_open_gate" = "yes" ] && [ -z "${KOSMOS_NO_OPEN:-}" ] && [ -z "${KOSMOS_APP_DIR:-}" ] \
   && { [ -z "${KOSMOS_SYS_APP_DIR:-}" ] || [ -n "${KOSMOS_OPEN_CMD:-}" ]; } \
   && bundle_is_ours "$APP_DIR/Kosmos.app" \
   && command -v "$OPEN_CMD" >/dev/null 2>&1; then
  _do_open=yes
fi

if [ "$_kosmos_board_off" = "yes" ] && [ "$BOARD_OURS" = "yes" ]; then
  # #4356: set not to run one, but a board of ours is up anyway (a stop that failed, or one started
  # by hand). Said as it is; the app stops it when it opens (stopBoardIfRunning).
  if [ "$_kosmos_mode_word" = connect ]; then
    printf '\n  Kosmos is installed. This computer is set not to run a board, but one is still running.\n'
    printf '  Open the Kosmos app from your Applications folder and it will stop it.\n\n'
  else
    printf '\n  Kosmos is installed. This computer'"'"'s setup choice could not be read, and a board is still running.\n'
    printf '  Open the Kosmos app from your Applications folder and it will ask how to set up this computer.\n\n'
  fi
elif [ "$_kosmos_board_off" = "yes" ]; then
  # #4356: no board on purpose. Not the "something else is on the port" branch below, whose
  # advice would start a board on a computer that connects elsewhere.
  if [ "$_kosmos_mode_word" = connect ]; then
    printf '\n  Kosmos is installed. No board of this install runs here, on purpose: this computer connects to agents on another computer.\n'
    printf '  Open the Kosmos app from your Applications folder.\n\n'
  else
    printf '\n  Kosmos is installed. No board was started, because this computer'"'"'s setup choice could not be read.\n'
    printf '  Open the Kosmos app from your Applications folder and it will ask how to set up this computer.\n\n'
  fi
elif [ "$_kosmos_started" = no ] && [ "$BOARD_OURS" != "yes" ]; then
  # #4356: this run did not start a board (the choice said not to when it looked), and the choice has
  # changed since. Not the "something else is on the port" branch below: nothing may be there.
  printf '\n  Kosmos is installed. Open the Kosmos app from your Applications folder to start it.\n\n'
elif [ "$BOARD_OURS" = "yes" ]; then
  printf '\n  Kosmos is running.\n'
  # #2073: app-only. The Kosmos app is the dashboard; the board URL is demoted to a
  # technical note (it still serves there for `kosmos open`), not presented as the
  # thing to open in a browser.
  # #3058: key the guidance on _do_open (the SAME predicate the launch block uses), not on
  # APP_MADE. When the app WILL auto-open, promise that and give the manual step only as a
  # fallback -- which is also the honest state over SSH/headless, where `open` is a documented
  # best-effort no-op. When it will NOT (a seeded update, a foreign/aliased bundle, no opener,
  # or a harness-suppressed open), print the bare imperative, which is the correct guidance for
  # exactly those cases. Keying on _do_open is what stops the summary and the launch disagreeing.
  if [ "$_do_open" = "yes" ]; then
    printf '  Kosmos will open to walk you through connecting your AI account.\n'
    printf '  If it does not appear, open the Kosmos app from your Applications folder.\n'
  else
    printf '  Open the Kosmos app from your Applications folder; it will walk you through connecting your AI account.\n'
  fi
  printf '  (Advanced: the board also serves at http://127.0.0.1:%s, which `kosmos open` uses.)\n\n' "$PORT"
else
  # 🛑 THE CAUSE IS NOT ASSERTED ANY MORE, and the old sentence was confidently
  # wrong for the likeliest stranger. It said "often another account's Kosmos",
  # which is true on a machine that already runs Kosmos and useless on one that
  # does not — and 4317 is the OpenTelemetry OTLP/gRPC default, so the people
  # most likely to hit this are the ones already running agents with a collector.
  # They would go looking for a second Kosmos that does not exist.
  # ⚠️ Same discipline as the connect screen: say what was observed (the port is
  # answering and it is not ours), name the candidates without ranking them, and
  # let the person recognise their own machine.
  # 🛑 AND THE OTLP HALF OF THAT SENTENCE IS GONE, because the default moved to
  # 16180 an hour after this was written and the sentence did not move with it.
  # It survived a first pass that fixed the same rot one screen earlier: a
  # correction does not sweep, and this one named a line rather than the class.
  printf '\n  Kosmos is installed, but something else is already answering on port %s,\n' "$PORT"
  printf '  so we did not start a board there. It could be another Kosmos (each\n'
  printf '  account runs its own), or any other program using that port.\n'
  if [ "$APP_MADE" = "yes" ]; then
    printf '  (The Kosmos icon this install created is tied to port %s and will open\n' "$PORT"
    printf '  whichever Kosmos answers there.)\n'
  fi
  printf '  Start yours on a different port, for example:\n'
  # 🛑 NOT PORT+1. The default is 4317 and 4318 is the OpenTelemetry OTLP/HTTP
  # default — so on the machine most likely to have 4317 taken, the escape hatch
  # pointed straight at the second-most-likely-occupied port on the box. An
  # escape that lands on the other landmine is worse than no suggestion.
  # 📌 Stepping well clear of the OTLP range rather than nudging by one.
  _alt=16181
  [ "$_alt" = "$PORT" ] && _alt=16182
  printf '    KOSMOS_PORT=%s %s/kosmos start\n' "$_alt" "$BIN_DIR"
  printf '  and it will print your dashboard address.\n\n'
fi
printf '  To remove it later:  curl -fsSL https://installkosmos.com/setup | sh -s -- --uninstall\n\n'

# ⚠️ A FRESH INSTALL ENDS LOOKING AT KOSMOS, NOT AT A PROMPT. Measured on the
# first real clean-machine run (2026-08-13): every step succeeded and the
# tester's report opened with "It did not open the window or the app" --
# for this installer's audience, a URL printed in a transcript is not a
# running product. Fresh installs only: yanking the app launch on an update
# would punish exactly the people who already know where the board is.
# Best-effort by design (`|| true`): over ssh or headless, `open` fails and
# the URL two lines up is still the whole answer.
#
# Launching the app is safe because the gate below requires BOARD_OURS:
# the pidfile proof above established that the thing answering the port
# is the board THIS install started, not merely something identifying as
# Kosmos (cmd_start's healthy() cannot tell those apart, which is exactly
# why the pidfile is the instrument). (install/kosmos's cmd_open is the
# other place this URL is spelled; keep the two together.)
#
# The launch predicate (_do_open) and its inputs -- OPEN_CMD, the enforcing-update gate
# (_open_gate) and the reauth-marker read -- were computed ABOVE, before the summary, so the
# summary line and this launch key on the SAME signal (#3058). The semantics they encode, kept
# here beside the launch action they govern:
#
# Two knobs. KOSMOS_NO_OPEN: any non-empty value suppresses the open (the harness exports it
# globally because a test that steals the operator's browser is a test nobody runs twice).
# KOSMOS_OPEN_CMD exists ONLY so the harness can substitute a recording stub and assert both
# legs; the sandbox app-dir overrides also suppress the open, with one carve-out -- a set
# KOSMOS_OPEN_CMD re-enables the SYS_APP_DIR probe passes, where the stub must observe the open.
# command -v (not -x) so a bare-name override like KOSMOS_OPEN_CMD=open does not silently no-op.
#
# #2023/#2073: also open ONCE on an enforcing UPDATE to establish the httpOnly board cookie
# #1946's enforcement requires. #2073 LAUNCHES THE APP (not a browser): the app reads the board
# token and appends ?token= itself, the board sets the cookie, and server.js seeds the reauth
# marker on that redemption -- so a normal update, WHEN THE APP WAS NOT ALREADY RUNNING, launches
# once and then _open_gate stops. Gated on a marker beside board.token so it fires on the FIRST
# update carrying this fix and never again (Max-Age 400 days; one seed carries every later update
# forward -- the "no launch per update" property). Enforcing-only: `-s board.token` present and
# non-empty is setup.sh's reading of enforced().
# ⚠️ RUNNING-APP EDGE, ACCEPTED: if the app is ALREADY running at update time, `open Kosmos.app`
# is an AppKit REOPEN that only re-shows the window -- no ?token= bootstrap, no seed, so the gate
# re-fires (window-to-front) on each later update until the next fresh relaunch. Low impact; the
# real fix is a Swift re-navigate-on-reopen, a native-app follow-up.
# ⚠️ #2028 EDGE, ACCEPTED: if the update did NOT refresh the bundle (make_app skipped -- aliased
# Applications, a foreign bundle), the launched app can be too old to carry tokenizedBoardURL, so
# it cannot seed and re-fires every update. The not-refreshed note earlier (APP_MADE != yes)
# points the user at the remedy.
if [ "$_do_open" = "yes" ]; then
  # #2073: only auto-launch OUR OWN app, and only when it exists. bundle_is_ours
  # (not a bare `-d`) because `-d` follows a symlink onto a FOREIGN Kosmos.app in
  # the multi-account / aliased-~/Applications case, where the resolver set
  # APP_DIR at a bundle it deliberately refused to claim -- launching a stranger's
  # app right after the transcript said we left it alone. bundle_is_ours refuses a
  # symlink and requires our KOSMOS_HOME anchor, so it: fires for our fresh or
  # already-current bundle (APP_MADE=no still has a valid app that must launch),
  # skips the make_app-failed case (no bundle -> the old browser fallback is gone,
  # so opening nothing beats naming an app that was not created; the APP_MADE=no
  # messaging above already guides recovery), AND skips the foreign bundle.
  # Named before it happens, per the header's every-step rule: the app window
  # appearing unannounced reads as "something went wrong". Under the .pkg,
  # postinstall may have the "Installing Kosmos" progress page open in the
  # browser (#662); #2073 makes installing.html stop turning itself into the
  # dashboard, so it stays a progress page and the app is the dashboard -- there
  # is no "second tab / becomes your dashboard" behaviour to reconcile any more.
  # #2073: Josh ruled Kosmos APP-ONLY, no browser. LAUNCH THE NATIVE APP instead of
  # opening a browser dashboard. Kosmos.app (staged into $APP_DIR by make_app above)
  # resolves the port, starts the board if it is not up, and loads it in its OWN
  # WebKit window -- and it reads the board token from its mode-600 file and appends
  # ?token= ITSELF (native-app/main.swift's tokenizedBoardURL), so the board sets the
  # enforcing httpOnly cookie and the app is authenticated on first paint. That
  # SUBSUMES the whole #1946/#1979/#2033 browser-nonce dance: no ?boot= mint, and the
  # token never reaches argv (the app reads it in-process), so the cross-account `ps`
  # exposure that dance existed to avoid cannot arise here at all. The #2023/#2030
  # reauth marker is now seeded on the app's ?token= redemption too (server.js), so
  # the enforcing-update gate above launches the app once and then stops.
  # The old messages ("Opening your dashboard in the browser", the ?boot mint, the
  # install-page "signing your browser in") are gone with the browser they described.
  printf '  Opening Kosmos...\n\n'
  # `_board_url` now holds the app bundle to hand `open`, not a URL -- the pkg
  # open-once plist and the direct-open fallback below both `open "$_board_url"`,
  # which launches the app. Kept the name to keep this diff to the open TARGET.
  _board_url="$APP_DIR/Kosmos.app"
  # 🛑 UNDER THE .PKG, NOT A BARE `open` (#663). Installer's postinstall runs
  # as root and drops to the person with `launchctl asuser` + `sudo -u`; the
  # first real fresh-account run (Josh, 2026-08-24) reached this line, said
  # "Opening your dashboard", and the browser stayed where it was. LaunchServices
  # from a root-descended shell is not the person's GUI session, whatever
  # asuser promises. The one mechanism Apple supports for an installer reaching
  # the person's desktop is a LaunchAgent bootstrapped into gui/<uid>: launchd
  # runs it INSIDE the login session, where `open` is ordinary. So in pkg mode
  # the open is a one-shot agent that launches the app, deletes its own plist,
  # and boots ITSELF out of launchd (#2151). The plist delete alone left the job
  # loaded-but-idle in launchd's registry until logout; the trailing `launchctl
  # bootout gui/<uid>/<label>` removes that residue too, so nothing of the
  # one-shot lingers. The BOARD_OURS gate above still decides whether
  # this runs at all; only the delivery changes. Everything else (paste
  # install, harness stub, sandbox) keeps the direct call.
  if [ "${KOSMOS_INSTALL_VIA:-}" = "pkg" ] && [ -z "${KOSMOS_OPEN_CMD:-}" ] && [ -z "${AGENT_WORKFORCE_LAUNCH:-}" ]; then
    _open_uid="$(/usr/bin/id -u)"
    _open_label=com.kosmos.open-once
    _open_dir="$HOME/Library/LaunchAgents"
    _open_plist="$_open_dir/$_open_label.plist"
    _open_url="$_board_url"
    # No pre-emptive removal of a stale open-once job here: the agent removes
    # itself, and if one is somehow still loaded the bootstrap below fails and
    # we fall back to a direct open. The install path must never contain a
    # removal of any launchd job (install.board-job.test.js: the update that
    # runs this installer is itself a launchd job).
    # #1946: create the token-bearing plist owner-only FROM THE FIRST BYTE via a
    # umask-scoped subshell (a plain `cat >` would create it at the default umask,
    # 644, and only the later chmod would tighten it -- a window). The subshell
    # keeps the umask change from leaking to the rest of the installer. The chmod
    # below still runs, for the case where a stale plist pre-existed (`cat >`
    # truncates it but does not change an existing file's mode).
    if mkdir -p "$_open_dir" 2>/dev/null && ( umask 077; cat > "$_open_plist" <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>$_open_label</string>
  <key>RunAtLoad</key><true/>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/sh</string>
    <string>-c</string>
    <string>/usr/bin/open "\$0"; rm -f "\$1"; /bin/launchctl bootout "gui/$_open_uid/$_open_label" 2>/dev/null</string>
    <string>$_open_url</string>
    <string>$_open_plist</string>
  </array>
</dict>
</plist>
PLIST
    )
    then
      # #2073: this plist's ProgramArguments now carry only $APP_DIR/Kosmos.app --
      # a non-secret bundle path, NOT a token or nonce (the app reads the board
      # token in-process). So the owner-only mode below is no longer guarding a
      # secret; it is kept as cheap belt-and-braces on a $HOME-group-traversable
      # LaunchAgents dir. (It used to matter: #1946's plist carried the token in a
      # ?token= URL, which is exactly the argv exposure #2073 removes.) The plist
      # self-removes (file + launchctl bootout) after RunAtLoad regardless (#2151).
      chmod 600 "$_open_plist" 2>/dev/null || true
      # The sandbox gate, restated within reach of the call (the sweep test
      # reads 12 lines above every launchctl): gui/<uid> is always the REAL
      # domain, so a harness must never get here. The enclosing if already
      # requires AGENT_WORKFORCE_LAUNCH unset; this is the belt.
      [ -z "${AGENT_WORKFORCE_LAUNCH:-}" ] || _open_plist=/dev/null/never
      if /bin/launchctl bootstrap "gui/$_open_uid" "$_open_plist" 2>/dev/null; then
        # Handed to the login session (RunAtLoad). This is the best open-success
        # signal available in pkg mode -- like a direct `open` returning 0, it
        # confirms dispatch, not navigation; that residual is documented at the seed.
        _opened=yes
        printf '  (handed to your login session as %s)\n\n' "$_open_label"
      else
        rm -f "$_open_plist"
        printf '  note: could not hand the open to your login session; trying directly.\n'
        if "$OPEN_CMD" "$_open_url" </dev/null >/dev/null 2>&1; then _opened=yes
        else printf '  note: Kosmos could not be opened automatically; open the Kosmos app from your Applications folder.\n\n'; fi
      fi
    else
      if "$OPEN_CMD" "$_open_url" </dev/null >/dev/null 2>&1; then _opened=yes
      else printf '  note: Kosmos could not be opened automatically; open the Kosmos app from your Applications folder.\n\n'; fi
    fi
  else
    # </dev/null: the spawned process must not inherit the curl|sh pipe --
    # the same class as cmd_start's measured never-returning install.
    if "$OPEN_CMD" "$_board_url" </dev/null >/dev/null 2>&1; then _opened=yes
    else printf '  note: Kosmos could not be opened automatically; open the Kosmos app from your Applications folder.\n\n'; fi
  fi
  # #2030: the repair marker is NOT seeded here (setup.sh could only see the launch
  # DISPATCHED, never REDEEMED); it is written server-side when a durable cookie is
  # truly taken (engine/boardauth.js seedReauthMarker, from server.js's bootstrap
  # handler) -- #2073: on the app's `?token=` redemption, and still on a `?boot=`.
  # #2073: this block LAUNCHES THE NATIVE APP (no mint, no `?boot=` browser dashboard)
  # in both the install-page (pkg) and non-pkg branches; the app authenticates via
  # `?token=` and that redemption seeds the marker server-side -- setup.sh's only job
  # here is to LAUNCH when the marker is absent (the gate above), and self-healing
  # falls out: an un-redeemed machine stays unseeded and re-launches on the next
  # update until one navigates (narrowed by the accepted running-app / #2028 edges).
  # (_opened is set on the open paths but no longer read here; #2073 removed the
  # nonce/mint tracking. Left set to keep this diff to the open TARGET.)
fi

# ---- the last thing on screen is the thing you still have to do (#1334) -------
#
# 🛑 A REQUIRED ACTION PLACED BEFORE A SUCCESS LINE IS READ AS PART OF THE
# SUCCESS. Observed on Josh's fresh Mac, 2026-08-28, on a DIFFERENT installer:
# it printed "successfully installed", then the PATH instruction, then
# "Installation complete!". He typed the command, got "command not found", and
# asked whether he was missing something. The eye goes success to success and
# the middle is read as decoration.
#
# ⚠️ OURS HAD A MILDER VERSION AND IT FIRED ON HIM TEN MINUTES LATER. We do the
# better thing first -- we wire the profile ourselves rather than asking -- but
# we said so about a thousand lines above here, and then finished on the
# dashboard address. In the window he was standing in, `kosmos` did not work.
#
# ⭐ THIS FILE ALREADY KNOWS THE RULE AND APPLIES IT ELSEWHERE. The
# printed-not-run banner is repeated at the bottom for exactly this reason, in
# its own words: "the bottom of the scroll is where the reader actually is."
# The PATH note simply never got the same treatment.
#
# 🔑 THE CONDITION IS MEASURED, NOT ASSUMED. Not "did we just wire it" -- that
# is a proxy, and it is wrong in both directions: a profile wired by an earlier
# install is not on this shell's PATH either, and a person whose PATH already
# carries it does not need telling. Asking whether BIN_DIR is on PATH *in this
# process* is the actual question, because this script runs from the user's
# shell, so its PATH is the one they are about to type into.
#
# 📌 It is not an error and it does not say "warning". Nothing failed: the board
# is running and the Kosmos app is open. The only thing wrong is that the person
# would reasonably conclude the install broke, so this replaces that conclusion
# rather than apologising for it.
case ":$PATH:" in
  *":$BIN_DIR:"*) ;;
  *)
    if [ -f "$BIN_DIR/kosmos" ] && [ -x "$BIN_DIR/kosmos" ]; then
      printf '  One more thing: typing "kosmos" works in a NEW Terminal window.\n'
      printf '  In this one, run:  export PATH="%s:$PATH"\n\n' "$BIN_DIR"
    fi
    ;;
esac
}

main "$@"

#
#   ------------------------------------------------------------------
#   IF YOU ARE READING THIS IN YOUR TERMINAL, KOSMOS DID NOT INSTALL.
#
#   Nothing went wrong and nothing was broken. This is the installer's
#   own text, printed to your screen instead of being run.
#
#   You need the whole line, including the part at the end:
#
#       curl -fsSL https://installkosmos.com/setup | sh
#
#   Copy that, paste it into Terminal, and press Return.
#   ------------------------------------------------------------------
#
# ⚠️ THE SAME THREE SENTENCES AS THE TOP OF THIS FILE, AND THE REPETITION IS THE
# POINT. When the script is printed instead of run, the reader is at the BOTTOM
# of the scroll -- the banner at line 3 is 2,145 lines above where they are
# looking, and somebody who believes the product just exploded does not scroll
# up through an installer to find out otherwise. Casey saw the tail (2026-08-22).
# Top for anyone who scrolls up, bottom for everyone else. It sits below the
# entry point, so the shell never reaches it and it costs nothing. (Shredder's
# catch: "the bottom of the scroll is where the reader actually is.")
#
# ⚠️ THE ENTRY POINT IS DELIBERATELY NOT QUOTED IN THIS COMMENT. Its own test
# finds it with `lastIndexOf`, so writing it here made the comment the last
# occurrence and the test reported the banner as sitting above the entry point.
# Describe it; do not spell it.