@jsonstudio/zterm-daemon-darwin-arm64 0.0.0-stage → 0.1.3

package/support/zterm-daemon.sh

@@ -0,0 +1,742 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PACKAGE_ROOT="$(python3 - "$PACKAGE_ROOT" <<'PY'
+import os, sys
+print(os.path.realpath(sys.argv[1]))
+PY
+)"
+NODE_BIN="$(command -v node)"
+LOG_DIR="${HOME}/.zterm/logs"
+WTERM_HOME="${HOME}/.zterm"
+WTERM_BIN_DIR="${WTERM_HOME}/bin"
+RUNTIME_STATE_DIR="${WTERM_HOME}/run"
+UPLOAD_DIR="${WTERM_HOME}/uploads"
+DOWNLOADS_DIR="${HOME}/Downloads/zterm"
+RUNTIME_DIR="${PACKAGE_ROOT}/runtime"
+DAEMON_PID_FILE="${RUNTIME_STATE_DIR}/zterm-daemon.pid"
+DIRECT_RUNNER="${WTERM_BIN_DIR}/zterm-daemon-run"
+LAUNCH_RUNNER="${WTERM_BIN_DIR}/zterm-daemon-launchd-run"
+LAUNCH_AGENT_LABEL="com.zterm.android.zterm-daemon"
+LAUNCH_AGENT_PATH="${HOME}/Library/LaunchAgents/${LAUNCH_AGENT_LABEL}.plist"
+PREVIOUS_LAUNCH_AGENT_LABEL="com.zterm.android.daemon"
+PREVIOUS_LAUNCH_AGENT_PATH="${HOME}/Library/LaunchAgents/${PREVIOUS_LAUNCH_AGENT_LABEL}.plist"
+LEGACY_LAUNCH_AGENT_LABEL="com.zterm.mobile.daemon"
+LEGACY_LAUNCH_AGENT_PATH="${HOME}/Library/LaunchAgents/${LEGACY_LAUNCH_AGENT_LABEL}.plist"
+STAGED_DAEMON_ENTRY="${RUNTIME_DIR}/server.cjs"
+TERMINAL_CONFIG_COMMAND="${PACKAGE_ROOT}/support/terminal-config-command.cjs"
+STAGED_NODE_PTY_HELPER_GLOB="${RUNTIME_DIR}/node_modules/node-pty/prebuilds/darwin-*/spawn-helper"
+NATIVE_DAEMON_BIN="${WTERM_BIN_DIR}/zterm-daemon"
+DAGPIPE_NATIVE_BIN="${RUNTIME_DIR}/dagpipe.node"
+ITERM2_PYTHON_VENV="${WTERM_HOME}/python/iterm2"
+ITERM2_PYTHON_BIN="${ITERM2_PYTHON_VENV}/bin/python3"
+
+read_config() {
+  "$NODE_BIN" "$TERMINAL_CONFIG_COMMAND" daemon-config --shell
+}
+
+config_output="$(read_config)"
+eval "$config_output"
+
+PROBE_SOCKET_HOST="$HOST"
+PROBE_URL_HOST="$HOST"
+case "$PROBE_SOCKET_HOST" in
+  0.0.0.0|::|\[::\])
+    PROBE_SOCKET_HOST="127.0.0.1"
+    PROBE_URL_HOST="127.0.0.1"
+    ;;
+  \[*\])
+    PROBE_SOCKET_HOST="${PROBE_SOCKET_HOST#[}"
+    PROBE_SOCKET_HOST="${PROBE_SOCKET_HOST%]}"
+    PROBE_URL_HOST="[${PROBE_SOCKET_HOST}]"
+    ;;
+  *:*)
+    PROBE_URL_HOST="[${PROBE_SOCKET_HOST}]"
+    ;;
+esac
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  zterm-daemon run
+  zterm-daemon start
+  zterm-daemon status
+  zterm-daemon config
+  zterm-daemon stop
+  zterm-daemon restart
+  zterm-daemon configure-relay --relay-url URL --username USER --password-stdin --host-id HOST_ID [--device-name NAME] [--restart-service]
+  zterm-daemon install-service
+  zterm-daemon uninstall-service
+  zterm-daemon service-status
+USAGE
+}
+
+configure_relay() {
+  local relay_url=""
+  local relay_username=""
+  local relay_password=""
+  local relay_host_id=""
+  local relay_device_id=""
+  local relay_device_name=""
+  local password_stdin="0"
+  local restart_after_config="0"
+
+  if [[ "${1:-}" == "configure-relay" ]]; then
+    shift
+  fi
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --relay-url)
+        relay_url="${2:-}"
+        shift 2
+        ;;
+      --username)
+        relay_username="${2:-}"
+        shift 2
+        ;;
+      --password)
+        echo "relay passwords are accepted only with --password-stdin" >&2
+        return 1
+        ;;
+      --password-stdin)
+        IFS= read -r relay_password
+        password_stdin="1"
+        shift
+        ;;
+      --password-env)
+        echo "relay passwords are accepted only with --password-stdin" >&2
+        return 1
+        ;;
+      --host-id)
+        relay_host_id="${2:-}"
+        shift 2
+        ;;
+      --device-id)
+        relay_device_id="${2:-}"
+        shift 2
+        ;;
+      --device-name)
+        relay_device_name="${2:-}"
+        shift 2
+        ;;
+      --restart-service)
+        restart_after_config="1"
+        shift
+        ;;
+      --no-restart)
+        restart_after_config="0"
+        shift
+        ;;
+      -h|--help)
+        usage
+        return 0
+        ;;
+      *)
+        echo "unknown configure-relay option: $1" >&2
+        return 1
+        ;;
+    esac
+  done
+
+  if [[ -z "$relay_url" || -z "$relay_username" || -z "$relay_password" || -z "$relay_host_id" || "$password_stdin" != "1" ]]; then
+    echo "configure-relay requires --relay-url, --username, --password-stdin, and --host-id" >&2
+    return 1
+  fi
+
+  local -a configure_args=(
+    "$TERMINAL_CONFIG_COMMAND"
+    configure-relay
+    --relay-url "$relay_url"
+    --username "$relay_username"
+    --host-id "$relay_host_id"
+    --password-stdin
+  )
+  if [[ -n "$relay_device_id" ]]; then
+    configure_args+=(--device-id "$relay_device_id")
+  fi
+  if [[ -n "$relay_device_name" ]]; then
+    configure_args+=(--device-name "$relay_device_name")
+  fi
+  printf '%s\n' "$relay_password" | "$NODE_BIN" "${configure_args[@]}"
+  if [[ "$restart_after_config" == "1" ]]; then
+    restart_service
+  else
+    echo "run 'zterm-daemon restart' after configuration to reconnect relay"
+  fi
+}
+
+service_installed() {
+  [[ -f "$LAUNCH_AGENT_PATH" ]]
+}
+
+service_loaded() {
+  launchctl print "gui/$(id -u)/${LAUNCH_AGENT_LABEL}" >/dev/null 2>&1
+}
+
+legacy_service_loaded() {
+  launchctl print "gui/$(id -u)/${LEGACY_LAUNCH_AGENT_LABEL}" >/dev/null 2>&1
+}
+
+previous_service_loaded() {
+  launchctl print "gui/$(id -u)/${PREVIOUS_LAUNCH_AGENT_LABEL}" >/dev/null 2>&1
+}
+
+service_snapshot() {
+  launchctl print "gui/$(id -u)/${LAUNCH_AGENT_LABEL}" 2>/dev/null || true
+}
+
+wait_for_service_ready() {
+  local attempts=0
+  local max_attempts=150
+  while (( attempts < max_attempts )); do
+    if daemon_health_ready; then
+      return 0
+    fi
+    sleep 0.2
+    attempts=$((attempts + 1))
+  done
+  return 1
+}
+
+wait_for_service_unloaded() {
+  local attempts=0
+  local max_attempts=30
+
+  while (( attempts < max_attempts )); do
+    if ! service_loaded; then
+      return 0
+    fi
+    sleep 0.2
+    attempts=$((attempts + 1))
+  done
+
+  return 1
+}
+
+port_listening() {
+  nc -z "${PROBE_SOCKET_HOST}" "${PORT}" >/dev/null 2>&1
+}
+
+daemon_health_ready() {
+  curl --silent --show-error --fail --max-time 2 "http://${PROBE_URL_HOST}:${PORT}/health" >/dev/null 2>&1
+}
+
+wait_for_port_closed() {
+  local attempts=0
+  local max_attempts=30
+  while (( attempts < max_attempts )); do
+    if ! port_listening; then
+      return 0
+    fi
+    sleep 0.2
+    attempts=$((attempts + 1))
+  done
+  return 1
+}
+
+reset_launch_crash_guard() {
+  rm -f "${RUNTIME_STATE_DIR}/zterm-daemon-launch-crashes.log"
+}
+
+read_daemon_pid() {
+  [[ -f "${DAEMON_PID_FILE}" ]] || return 1
+  local pid
+  pid="$(tr -d '[:space:]' < "${DAEMON_PID_FILE}")"
+  [[ -n "${pid}" ]] || return 1
+  printf '%s\n' "${pid}"
+}
+
+is_process_running() {
+  local pid="${1:-}"
+  [[ -n "${pid}" ]] || return 1
+  kill -0 "${pid}" >/dev/null 2>&1
+}
+
+run_foreground() {
+  mkdir -p "$LOG_DIR"
+  chmod +x ${STAGED_NODE_PTY_HELPER_GLOB} 2>/dev/null || true
+  cd "${HOME}"
+  exec env -u TMUX -u TMUX_PANE HOST="$HOST" PORT="$PORT" ZTERM_HOST="$HOST" ZTERM_PORT="$PORT" ZTERM_AUTH_TOKEN="${ZTERM_AUTH_TOKEN:-}" ZTERM_DAEMON_NATIVE="$NATIVE_DAEMON_BIN" ZTERM_DAGPIPE_NATIVE="${DAGPIPE_NATIVE_BIN}" "$NODE_BIN" "$STAGED_DAEMON_ENTRY"
+}
+
+status_direct() {
+  local pid=""
+  if pid="$(read_daemon_pid 2>/dev/null)" && is_process_running "${pid}" && port_listening; then
+    echo "zterm daemon running: pid=${pid} host=${HOST} port=${PORT} auth=${AUTH_SOURCE}"
+    return 0
+  fi
+  if [[ -n "${pid}" ]] && ! is_process_running "${pid}"; then
+    rm -f "${DAEMON_PID_FILE}"
+  fi
+  if port_listening; then
+    echo "zterm daemon listener is up on port ${PORT}, but managed pid truth is missing"
+    echo "pidFile=${DAEMON_PID_FILE} host=${HOST} auth=${AUTH_SOURCE}"
+    return 1
+  fi
+  echo "zterm daemon not running (${PORT})"
+  echo "config=${CONFIG_DISPLAY_PATH} found=${CONFIG_FOUND} auth=${AUTH_SOURCE}"
+  return 1
+}
+
+status_service() {
+  if ! service_installed; then
+    echo "zterm autostart service not installed"
+    echo "plist=${LAUNCH_AGENT_PATH}"
+    return 1
+  fi
+  local snapshot last_exit active_count
+  snapshot="$(service_snapshot)"
+  last_exit="$(printf '%s\n' "$snapshot" | awk '/last exit code =/ { print $5; exit }')"
+  active_count="$(printf '%s\n' "$snapshot" | awk '/active count =/ { print $4; exit }')"
+  if [[ "${active_count:-0}" != "0" ]] && daemon_health_ready; then
+    echo "zterm autostart service running: label=${LAUNCH_AGENT_LABEL} host=${HOST} port=${PORT} auth=${AUTH_SOURCE}"
+    echo "plist=${LAUNCH_AGENT_PATH}"
+    echo "active_count=${active_count:-unknown} last_exit=${last_exit:-unknown}"
+    return 0
+  fi
+  echo "zterm autostart service installed but unhealthy: label=${LAUNCH_AGENT_LABEL}"
+  echo "plist=${LAUNCH_AGENT_PATH}"
+  echo "active_count=${active_count:-unknown} last_exit=${last_exit:-unknown}"
+  echo "health=down url=http://${PROBE_URL_HOST}:${PORT}/health"
+  return 1
+}
+
+status() {
+  if service_installed; then
+    if status_service; then
+      return 0
+    fi
+    status_direct
+    return $?
+  fi
+  status_direct
+}
+
+start_direct() {
+  mkdir -p "$LOG_DIR" "$RUNTIME_STATE_DIR"
+  local timestamp log_file
+  timestamp="$(date +%Y%m%d-%H%M%S)"
+  log_file="${LOG_DIR}/daemon-${PORT}-${timestamp}.log"
+  local existing_pid=""
+  if existing_pid="$(read_daemon_pid 2>/dev/null)" && is_process_running "${existing_pid}" && port_listening; then
+    echo "zterm daemon already running: pid=${existing_pid} host=${HOST} port=${PORT} auth=${AUTH_SOURCE}"
+    echo "pidFile=${DAEMON_PID_FILE}"
+    return 0
+  fi
+  if [[ -n "${existing_pid}" ]] && ! is_process_running "${existing_pid}"; then
+    rm -f "${DAEMON_PID_FILE}"
+  fi
+  if port_listening; then
+    echo "zterm daemon listener already exists on port ${PORT}, but managed pid truth is missing"
+    echo "pidFile=${DAEMON_PID_FILE}"
+    return 1
+  fi
+  chmod +x ${STAGED_NODE_PTY_HELPER_GLOB} 2>/dev/null || true
+  (
+    cd "${HOME}"
+    env -u TMUX -u TMUX_PANE HOST="$HOST" PORT="$PORT" ZTERM_HOST="$HOST" ZTERM_PORT="$PORT" ZTERM_AUTH_TOKEN="${ZTERM_AUTH_TOKEN:-}" ZTERM_DAEMON_NATIVE="$NATIVE_DAEMON_BIN" \
+      "$NODE_BIN" "$STAGED_DAEMON_ENTRY" >>"$log_file" 2>&1
+  ) &
+  local daemon_pid=$!
+  printf '%s\n' "${daemon_pid}" > "${DAEMON_PID_FILE}"
+  if ! wait_for_service_ready; then
+    if is_process_running "${daemon_pid}"; then
+      kill "${daemon_pid}" >/dev/null 2>&1 || true
+      wait "${daemon_pid}" 2>/dev/null || true
+    fi
+    rm -f "${DAEMON_PID_FILE}"
+    echo "zterm daemon failed to become ready on port ${PORT}"
+    echo "log=${log_file}"
+    return 1
+  fi
+  echo "zterm daemon started"
+  echo "pid=${daemon_pid}"
+  echo "host=${HOST}"
+  echo "port=${PORT}"
+  echo "auth=${AUTH_SOURCE}"
+  echo "config=${CONFIG_DISPLAY_PATH}"
+  echo "pidFile=${DAEMON_PID_FILE}"
+  echo "log=${log_file}"
+}
+
+stop_direct() {
+  local pid=""
+  if ! pid="$(read_daemon_pid 2>/dev/null)"; then
+    if port_listening; then
+      echo "zterm daemon listener is up on port ${PORT}, but managed pid truth is missing"
+      echo "pidFile=${DAEMON_PID_FILE}"
+      return 1
+    fi
+    echo "zterm daemon not running (${PORT})"
+    return 0
+  fi
+  if ! is_process_running "${pid}"; then
+    rm -f "${DAEMON_PID_FILE}"
+    if port_listening; then
+      echo "zterm daemon listener is up on port ${PORT}, but pid ${pid} is stale"
+      return 1
+    fi
+    echo "zterm daemon not running (${PORT})"
+    return 0
+  fi
+  kill "${pid}"
+  if ! wait_for_port_closed; then
+    echo "zterm daemon did not stop listening on port ${PORT} after pid ${pid} was terminated"
+    return 1
+  fi
+  wait "${pid}" 2>/dev/null || true
+  rm -f "${DAEMON_PID_FILE}"
+  echo "zterm daemon stopped: pid=${pid}"
+}
+
+prepare_iterm2_python_env() {
+  if [[ "$(uname -s)" != "Darwin" ]]; then
+    return 0
+  fi
+  mkdir -p "${WTERM_HOME}/python"
+  if [[ ! -x "$ITERM2_PYTHON_BIN" ]]; then
+    python3 -m venv "$ITERM2_PYTHON_VENV"
+  fi
+  if "$ITERM2_PYTHON_BIN" - <<'PY' >/dev/null 2>&1
+import iterm2
+PY
+  then
+    return 0
+  fi
+  "$ITERM2_PYTHON_BIN" -m pip install --upgrade pip >/dev/null
+  "$ITERM2_PYTHON_BIN" -m pip install --upgrade iterm2
+}
+
+write_launch_agent() {
+  prepare_iterm2_python_env || echo "[zterm-daemon] iTerm2 Python API environment unavailable; remote-window pane catalog will report an explicit error" >&2
+  mkdir -p "${HOME}/Library/LaunchAgents" "$LOG_DIR" "$WTERM_BIN_DIR" "$RUNTIME_STATE_DIR"
+  cat > "$DIRECT_RUNNER" <<RUNNER
+#!/usr/bin/env bash
+set -euo pipefail
+cd "${HOME}"
+export PATH="${HOME}/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+chmod +x ${STAGED_NODE_PTY_HELPER_GLOB} 2>/dev/null || true
+exec env -u TMUX -u TMUX_PANE ZTERM_ITERM2_PYTHON="${ITERM2_PYTHON_BIN}" ZTERM_DAEMON_NATIVE="${NATIVE_DAEMON_BIN}" ZTERM_DAGPIPE_NATIVE="${DAGPIPE_NATIVE_BIN}" "${NODE_BIN}" "${STAGED_DAEMON_ENTRY}"
+RUNNER
+  chmod +x "$DIRECT_RUNNER"
+
+  cat > "$LAUNCH_RUNNER" <<RUNNER
+#!/usr/bin/env bash
+set -euo pipefail
+PORT="${PORT}"
+PROBE_URL_HOST="${PROBE_URL_HOST}"
+STATE_DIR="${RUNTIME_STATE_DIR}"
+CRASH_FILE="${RUNTIME_STATE_DIR}/zterm-daemon-launch-crashes.log"
+mkdir -p "\$STATE_DIR"
+health_ready() {
+  curl --silent --show-error --fail --max-time 2 "http://\${PROBE_URL_HOST}:\${PORT}/health" >/dev/null 2>&1
+}
+if health_ready; then
+  echo "[\$(date -u +%Y-%m-%dT%H:%M:%SZ)] launchd preflight: health ok on port \$PORT, skip duplicate start" >> "${LOG_DIR}/launchd-stdout.log"
+  exit 0
+fi
+RECENT_LAUNCHES="\$(
+  if [[ -f "\$CRASH_FILE" ]]; then
+    python3 - "\$CRASH_FILE" "\$(date +%s)" <<'PY'
+import pathlib, sys
+path = pathlib.Path(sys.argv[1])
+now = int(sys.argv[2])
+cutoff = now - 120
+entries = []
+for line in path.read_text().splitlines():
+    try:
+        value = int(line.strip())
+    except ValueError:
+        continue
+    if value >= cutoff:
+        entries.append(value)
+entries.append(now)
+path.write_text("\n".join(str(item) for item in entries[-8:]) + "\n")
+print(len(entries))
+PY
+  else
+    printf '%s\n' "\$(date +%s)" > "\$CRASH_FILE"
+    echo 1
+  fi
+)"
+if [[ "\${RECENT_LAUNCHES:-0}" -ge 5 ]]; then
+  echo "[\$(date -u +%Y-%m-%dT%H:%M:%SZ)] launchd preflight: crash-loop guard tripped (\${RECENT_LAUNCHES} launches/120s), stop auto-restart" >> "${LOG_DIR}/launchd-stderr.log"
+  exit 0
+fi
+cd "${HOME}"
+export PATH="${HOME}/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+chmod +x ${STAGED_NODE_PTY_HELPER_GLOB} 2>/dev/null || true
+child_pid=""
+terminate_child() {
+  [[ -n "\${child_pid}" ]] || return 0
+  kill -0 "\${child_pid}" >/dev/null 2>&1 || return 0
+  kill -TERM "\${child_pid}" >/dev/null 2>&1 || true
+  for _ in 1 2 3 4 5; do
+    kill -0 "\${child_pid}" >/dev/null 2>&1 || break
+    sleep 1
+  done
+  if kill -0 "\${child_pid}" >/dev/null 2>&1; then
+    kill -KILL "\${child_pid}" >/dev/null 2>&1 || true
+  fi
+  wait "\${child_pid}" >/dev/null 2>&1 || true
+}
+cleanup_child() {
+  terminate_child
+}
+trap cleanup_child TERM INT
+env -u TMUX -u TMUX_PANE ZTERM_ITERM2_PYTHON="${ITERM2_PYTHON_BIN}" ZTERM_DAEMON_NATIVE="${NATIVE_DAEMON_BIN}" ZTERM_DAGPIPE_NATIVE="${DAGPIPE_NATIVE_BIN}" "${NODE_BIN}" "${STAGED_DAEMON_ENTRY}" &
+child_pid="\$!"
+missed_health_checks=0
+child_start_epoch="\$(date +%s)"
+STARTUP_HEALTH_GRACE_SECONDS=45
+while kill -0 "\${child_pid}" >/dev/null 2>&1; do
+  if health_ready; then
+    missed_health_checks=0
+  else
+    now_epoch="\$(date +%s)"
+    child_age=\$((now_epoch - child_start_epoch))
+    if [[ "\${child_age}" -lt "\${STARTUP_HEALTH_GRACE_SECONDS}" ]]; then
+      echo "[\$(date -u +%Y-%m-%dT%H:%M:%SZ)] launchd watchdog: waiting for startup health child=\${child_pid} age=\${child_age}s" >> "${LOG_DIR}/launchd-stderr.log"
+      missed_health_checks=0
+    else
+      missed_health_checks=\$((missed_health_checks + 1))
+      echo "[\$(date -u +%Y-%m-%dT%H:%M:%SZ)] launchd watchdog: missed health check \${missed_health_checks}/3 for child \${child_pid}" >> "${LOG_DIR}/launchd-stderr.log"
+      if [[ "\${missed_health_checks}" -ge 3 ]]; then
+        echo "[\$(date -u +%Y-%m-%dT%H:%M:%SZ)] launchd watchdog: restarting unhealthy child \${child_pid}" >> "${LOG_DIR}/launchd-stderr.log"
+        terminate_child
+        exit 1
+      fi
+    fi
+  fi
+  sleep 10
+done
+wait "\${child_pid}"
+exit "\$?"
+RUNNER
+  chmod +x "$LAUNCH_RUNNER"
+
+  cat > "$LAUNCH_AGENT_PATH" <<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>${LAUNCH_AGENT_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${LAUNCH_RUNNER}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>60</integer>
+  <key>StandardOutPath</key>
+  <string>${LOG_DIR}/launchd-stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>${LOG_DIR}/launchd-stderr.log</string>
+</dict>
+</plist>
+PLIST
+}
+
+stop_legacy_service() {
+  if previous_service_loaded; then
+    launchctl bootout "gui/$(id -u)" "$PREVIOUS_LAUNCH_AGENT_PATH" || launchctl bootout "gui/$(id -u)/${PREVIOUS_LAUNCH_AGENT_LABEL}" || true
+  fi
+  if legacy_service_loaded; then
+    launchctl bootout "gui/$(id -u)" "$LEGACY_LAUNCH_AGENT_PATH" || launchctl bootout "gui/$(id -u)/${LEGACY_LAUNCH_AGENT_LABEL}" || true
+  fi
+}
+
+remove_legacy_service() {
+  stop_legacy_service
+  rm -f "$PREVIOUS_LAUNCH_AGENT_PATH"
+  rm -f "$LEGACY_LAUNCH_AGENT_PATH"
+}
+
+bootstrap_service() {
+  reset_launch_crash_guard
+  launchctl bootstrap "gui/$(id -u)" "$LAUNCH_AGENT_PATH"
+}
+
+prime_daemon_install_permissions() {
+  if [[ "$(uname -s)" != "Darwin" ]]; then
+    return 0
+  fi
+
+  echo "zterm daemon install permission preflight"
+  echo "- macOS file sync uses this daemon process to read/write user-selected paths."
+  echo "- Grant file access to Terminal/iTerm or the installed daemon runner when macOS prompts."
+  echo "- Screen Recording and remote window capture use zterm-daemon directly."
+
+  mkdir -p "$WTERM_HOME" "$UPLOAD_DIR" "$DOWNLOADS_DIR"
+  ZTERM_DAEMON_NATIVE="$NATIVE_DAEMON_BIN" "$NODE_BIN" - <<'NODE'
+const { accessSync, constants, mkdirSync, rmSync, writeFileSync, unlinkSync } = require('node:fs');
+const { execFileSync } = require('node:child_process');
+const { join } = require('node:path');
+const { homedir } = require('node:os');
+
+const dirs = [
+  join(homedir(), '.zterm'),
+  join(homedir(), 'Downloads', 'zterm'),
+];
+
+for (const dir of dirs) {
+  mkdirSync(dir, { recursive: true });
+  accessSync(dir, constants.R_OK | constants.W_OK);
+  const probe = join(dir, '.zterm-permission-preflight');
+  writeFileSync(probe, 'ok\n');
+  unlinkSync(probe);
+}
+
+try {
+  if (!process.env.ZTERM_DAEMON_NATIVE) {
+    throw new Error('installed ScreenCaptureKit capture binary is required');
+  }
+  execFileSync(process.env.ZTERM_DAEMON_NATIVE, ['--permission-probe'], {
+    stdio: 'pipe',
+    timeout: 180000,
+  });
+} catch (error) {
+  const stderr = error && error.stderr ? String(error.stderr) : '';
+  const message = error && error.message ? String(error.message) : String(error);
+  const timedOut = /ETIMEDOUT|timed out/u.test(message);
+  console.error(timedOut
+    ? 'ScreenCaptureKit permission was not granted before the 180s deadline.'
+    : 'ScreenCaptureKit permission preflight failed.');
+  console.error('Grant Screen Recording to ' + process.env.ZTERM_DAEMON_NATIVE + ' in System Settings -> Privacy & Security -> Screen & System Audio Recording by clicking + and adding that exact file. macOS 26 refused to show a grant dialog for this binary, so the add button is the supported path.');
+  if (stderr.trim()) console.error(stderr.trim());
+  if (message.trim()) console.error(message.trim());
+  process.exit(1);
+}
+NODE
+}
+
+start_service() {
+  if ! service_installed; then
+    echo "zterm autostart service not installed"
+    echo "run: zterm-daemon install-service"
+    return 1
+  fi
+  stop_direct >/dev/null 2>&1 || true
+  remove_legacy_service
+  write_launch_agent
+  if service_loaded; then
+    launchctl bootout "gui/$(id -u)/${LAUNCH_AGENT_LABEL}" >/dev/null 2>&1 || true
+    wait_for_service_unloaded || {
+      echo "zterm autostart service failed to unload before start"
+      return 1
+    }
+  fi
+  bootstrap_service
+  if wait_for_service_ready; then
+    status_service
+    return 0
+  fi
+  echo "zterm autostart service unhealthy after start"
+  launchctl bootout "gui/$(id -u)/${LAUNCH_AGENT_LABEL}" >/dev/null 2>&1 || true
+  return 1
+}
+
+stop_service() {
+  if ! service_installed; then
+    echo "zterm autostart service not installed"
+    return 0
+  fi
+  if service_loaded; then
+    launchctl bootout "gui/$(id -u)/${LAUNCH_AGENT_LABEL}"
+  fi
+  echo "zterm autostart service stopped: label=${LAUNCH_AGENT_LABEL}"
+}
+
+restart_service() {
+  if ! service_installed; then
+    echo "zterm autostart service not installed"
+    echo "run: zterm-daemon install-service"
+    return 1
+  fi
+  stop_direct >/dev/null 2>&1 || true
+  remove_legacy_service
+  write_launch_agent
+  if service_loaded; then
+    launchctl bootout "gui/$(id -u)/${LAUNCH_AGENT_LABEL}"
+    wait_for_service_unloaded || {
+      echo "zterm autostart service failed to unload before restart"
+      return 1
+    }
+  fi
+  bootstrap_service
+  if wait_for_service_ready; then
+    status_service
+    return 0
+  fi
+  echo "zterm autostart service unhealthy after restart"
+  launchctl bootout "gui/$(id -u)/${LAUNCH_AGENT_LABEL}" >/dev/null 2>&1 || true
+  return 1
+}
+
+install_service() {
+  stop_direct >/dev/null 2>&1 || true
+  remove_legacy_service
+  write_launch_agent
+  prime_daemon_install_permissions
+  if service_loaded; then
+    launchctl bootout "gui/$(id -u)/${LAUNCH_AGENT_LABEL}"
+    wait_for_service_unloaded || {
+      echo "zterm autostart service failed to unload before install"
+      return 1
+    }
+  fi
+  bootstrap_service
+  echo "zterm autostart service installed"
+  echo "plist=${LAUNCH_AGENT_PATH}"
+  if wait_for_service_ready; then
+    status_service
+    return 0
+  fi
+  echo "zterm autostart service unhealthy after install"
+  launchctl bootout "gui/$(id -u)/${LAUNCH_AGENT_LABEL}" >/dev/null 2>&1 || true
+  return 1
+}
+
+uninstall_service() {
+  if service_loaded; then
+    launchctl bootout "gui/$(id -u)/${LAUNCH_AGENT_LABEL}"
+  fi
+  remove_legacy_service
+  rm -f "$LAUNCH_AGENT_PATH"
+  echo "zterm autostart service uninstalled"
+  echo "plist=${LAUNCH_AGENT_PATH}"
+}
+
+cmd="${1:-}"
+if [[ "$cmd" == "--" ]]; then
+  shift
+  cmd="${1:-}"
+fi
+
+case "$cmd" in
+  run) run_foreground ;;
+  start) start_service ;;
+  status) status ;;
+  stop) stop_service ;;
+  restart) restart_service ;;
+  config) "$NODE_BIN" "$TERMINAL_CONFIG_COMMAND" daemon-config ;;
+  configure-relay) configure_relay "$@" ;;
+  install-service) install_service ;;
+  uninstall-service) uninstall_service ;;
+  service-status) status_service ;;
+  ""|-h|--help|help) usage ;;
+  *)
+    echo "unknown command: $cmd" >&2
+    usage >&2
+    exit 1
+    ;;
+esac