zl-code 0.0.30 → 0.0.32

package/dist/npm-service-runtime.sh

@@ -0,0 +1,808 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+SCRIPT_PATH="$(readlink -f "${BASH_SOURCE[0]}")"
+SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+REPO_DIR="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd)"
+
+RUNTIME_ROOT="${ZL_CODE_NPM_SERVICE_ROOT:-${HOME}/.local/share/zl-code}"
+PRODUCTION_HOME="${ZL_CODE_NPM_SERVICE_HOME:-${HOME}/.zettai-labs-code}"
+OPERATOR_STATE="${ZL_CODE_NPM_SERVICE_STATE_DIR:-${HOME}/.local/state/zl-code/npm-service}"
+UNIT_PATH="${ZL_CODE_NPM_SERVICE_UNIT_PATH:-${HOME}/.config/systemd/user/zl-code-server.service}"
+DEFAULT_UNIT_TEMPLATE="${REPO_DIR}/infra/systemd/zl-code-server-npm.service"
+[[ -f "${SCRIPT_DIR}/zl-code-server-npm.service" ]] && DEFAULT_UNIT_TEMPLATE="${SCRIPT_DIR}/zl-code-server-npm.service"
+UNIT_TEMPLATE="${ZL_CODE_NPM_SERVICE_UNIT_TEMPLATE:-${DEFAULT_UNIT_TEMPLATE}}"
+SUPERVISOR_UNIT_PATH="${ZL_CODE_UPDATE_SUPERVISOR_UNIT_PATH:-${HOME}/.config/systemd/user/zl-code-update-supervisor.service}"
+DEFAULT_SUPERVISOR_UNIT_TEMPLATE="${REPO_DIR}/infra/systemd/zl-code-update-supervisor.service"
+[[ -f "${SCRIPT_DIR}/zl-code-update-supervisor.service" ]] && DEFAULT_SUPERVISOR_UNIT_TEMPLATE="${SCRIPT_DIR}/zl-code-update-supervisor.service"
+SUPERVISOR_UNIT_TEMPLATE="${ZL_CODE_UPDATE_SUPERVISOR_UNIT_TEMPLATE:-${DEFAULT_SUPERVISOR_UNIT_TEMPLATE}}"
+SUPERVISOR_SERVICE_NAME="${ZL_CODE_UPDATE_SUPERVISOR_SERVICE_NAME:-zl-code-update-supervisor.service}"
+NODE_BIN="${ZL_CODE_NPM_SERVICE_NODE_BIN:-${HOME}/.local/share/mise/installs/node/24.19.0/bin/node}"
+NPM_BIN="${ZL_CODE_NPM_SERVICE_NPM_BIN:-${HOME}/.local/share/mise/installs/node/24.19.0/bin/npm}"
+SERVICE_NAME="${ZL_CODE_NPM_SERVICE_NAME:-zl-code-server.service}"
+LOCAL_URL="${ZL_CODE_NPM_SERVICE_LOCAL_URL:-http://127.0.0.1:14773/}"
+PUBLIC_URL="${ZL_CODE_NPM_SERVICE_PUBLIC_URL:-https://code.zettailabs.com/}"
+RESTART_STATE_FILE="${ZL_CODE_NPM_SERVICE_RESTART_STATE_FILE:-${PRODUCTION_HOME}/userdata/server-restart.json}"
+DRAIN_SIGNAL="${ZL_CODE_NPM_SERVICE_DRAIN_SIGNAL:-SIGUSR1}"
+DRAIN_ACK_TIMEOUT_SECONDS="${ZL_CODE_NPM_SERVICE_DRAIN_ACK_TIMEOUT_SECONDS:-10}"
+DRAIN_QUIESCE_TIMEOUT_SECONDS="${ZL_CODE_NPM_SERVICE_DRAIN_QUIESCE_TIMEOUT_SECONDS:-10}"
+LOCK_FILE="${OPERATOR_STATE}/operation.lock"
+ROLLBACK_DIR="${OPERATOR_STATE}/rollback"
+TRANSACTION_DIR="${OPERATOR_STATE}/transaction"
+LOCK_HELD=false
+SUPERVISED_MODE=false
+ACTIVATION_BOUNDARY_CAPTURED=false
+ACTIVATION_CUTOVER_STARTED=false
+ACTIVATION_ROLLBACK_COMPLETED=false
+SUPERVISED_ROLLBACK_VERSION=""
+
+usage() {
+  cat <<'EOF'
+Manage the versioned npm runtime for the local Zettai Labs Code service.
+
+Usage:
+  scripts/npm-service-runtime.sh status
+  scripts/npm-service-runtime.sh prepare <version> --no-cutover
+  scripts/npm-service-runtime.sh backup
+  scripts/npm-service-runtime.sh activate <version> --backup-dir <path> --confirm-cutover
+  scripts/npm-service-runtime.sh verify <version>
+  scripts/npm-service-runtime.sh rollback --to previous|git --confirm-cutover
+  scripts/npm-service-runtime.sh supervised-update <version> --confirm-supervised
+  scripts/npm-service-runtime.sh install-supervisor --confirm-install
+
+`prepare` and `backup` never reload or restart systemd. `activate` and
+`rollback` refuse to run without the literal --confirm-cutover flag.
+EOF
+}
+
+fail() {
+  echo "error: $*" >&2
+  exit 1
+}
+
+log() {
+  printf '\n==> %s\n' "$*"
+}
+
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || fail "required command not found: $1"
+}
+
+require_file() {
+  [[ -f "$1" ]] || fail "required file not found: $1"
+}
+
+require_executable() {
+  [[ -x "$1" ]] || fail "required executable not found: $1"
+}
+
+acquire_lock() {
+  [[ "$LOCK_HELD" == true ]] && return
+  mkdir -p "$OPERATOR_STATE"
+  chmod 700 "$OPERATOR_STATE"
+  exec 9>"$LOCK_FILE"
+  flock -n 9 || fail "another npm service operation is running"
+  LOCK_HELD=true
+}
+
+emit_supervisor_phase() {
+  [[ "$SUPERVISED_MODE" == true ]] || return 0
+  echo "supervisor_phase=$1"
+}
+
+validate_version() {
+  [[ "$1" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]] ||
+    fail "invalid exact npm version: $1"
+}
+
+validate_operation_id() {
+  [[ "$1" =~ ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ]] ||
+    fail "invalid supervised update operation id"
+}
+
+release_dir() {
+  printf '%s/releases/%s\n' "$RUNTIME_ROOT" "$1"
+}
+
+package_entry() {
+  printf '%s/node_modules/zl-code/dist/bin.mjs\n' "$(release_dir "$1")"
+}
+
+atomic_symlink() {
+  local target=$1
+  local link_path=$2
+  local temporary="${link_path}.tmp.$$"
+  mkdir -p "$(dirname "$link_path")"
+  rm -f "$temporary"
+  ln -s "$target" "$temporary"
+  mv -Tf "$temporary" "$link_path"
+}
+
+read_current_release_identity() {
+  local package_path="${RUNTIME_ROOT}/current/node_modules/zl-code/package.json"
+  if [[ ! -f "$package_path" ]]; then
+    printf 'release:absent\n'
+    return
+  fi
+  printf 'release:%s\n' "$($NODE_BIN -e 'const p=require(process.argv[1]); process.stdout.write(String(p.version ?? ""))' "$package_path")"
+}
+
+write_restart_state() {
+  local restart_id=$1
+  local initiator=$2
+  local current_sha=$3
+  local target_sha=$4
+  local requested_at=$5
+  mkdir -p "$(dirname "$RESTART_STATE_FILE")"
+  "$NODE_BIN" - "$RESTART_STATE_FILE" "$restart_id" "$initiator" "$current_sha" "$target_sha" "$requested_at" <<'NODE'
+const fs = require("node:fs");
+const [file, restartId, initiator, currentSha, targetSha, requestedAt] = process.argv.slice(2);
+const state = {
+  version: 1,
+  reason: "update",
+  restartId,
+  initiator,
+  currentSha,
+  targetSha,
+  requestedAt,
+};
+fs.writeFileSync(file, `${JSON.stringify(state)}\n`);
+NODE
+}
+
+patch_restart_state() {
+  local patch=$1
+  "$NODE_BIN" - "$RESTART_STATE_FILE" "$patch" <<'NODE'
+const fs = require("node:fs");
+const [file, rawPatch] = process.argv.slice(2);
+const patch = JSON.parse(rawPatch);
+const current = JSON.parse(fs.readFileSync(file, "utf8"));
+fs.writeFileSync(file, `${JSON.stringify({ ...current, ...patch })}\n`);
+NODE
+}
+
+read_restart_state_field() {
+  local field=$1
+  "$NODE_BIN" - "$RESTART_STATE_FILE" "$field" <<'NODE'
+const fs = require("node:fs");
+const [file, field] = process.argv.slice(2);
+const state = JSON.parse(fs.readFileSync(file, "utf8"));
+const value = state[field];
+if (value === undefined || value === null) {
+  process.exit(1);
+}
+process.stdout.write(String(value));
+NODE
+}
+
+await_restart_state_field() {
+  local field=$1
+  local timeout_seconds=$2
+  local attempt=1
+  while [[ "$attempt" -le "$timeout_seconds" ]]; do
+    if read_restart_state_field "$field" >/dev/null; then
+      return 0
+    fi
+    sleep 1
+    attempt=$((attempt + 1))
+  done
+  return 1
+}
+
+verify_release() {
+  local version=$1
+  local directory
+  local entry
+  local reported
+  directory="$(release_dir "$version")"
+  entry="$(package_entry "$version")"
+  require_file "$directory/node_modules/zl-code/package.json"
+  require_file "$entry"
+  reported="$($NODE_BIN -e 'const p=require(process.argv[1]); process.stdout.write(p.name+"@"+p.version)' "$directory/node_modules/zl-code/package.json")"
+  [[ "$reported" == "zl-code@${version}" ]] || fail "release identity mismatch: $reported"
+  reported="$($NODE_BIN "$entry" --version)"
+  [[ "$reported" == "zl-code v${version}" ]] || fail "CLI identity mismatch: $reported"
+}
+
+prepare_release() {
+  local version=$1
+  local no_cutover=$2
+  local directory
+  local temporary
+  [[ "$no_cutover" == true ]] || fail "prepare requires --no-cutover"
+  validate_version "$version"
+  acquire_lock
+  require_executable "$NODE_BIN"
+  require_executable "$NPM_BIN"
+  require_command mv
+  export PATH="$(dirname "$NODE_BIN"):${PATH}"
+
+  directory="$(release_dir "$version")"
+  mkdir -p "$RUNTIME_ROOT/releases"
+  chmod 700 "$RUNTIME_ROOT" "$RUNTIME_ROOT/releases"
+
+  if [[ ! -d "$directory" ]]; then
+    temporary="${RUNTIME_ROOT}/releases/.${version}.prepare.$$"
+    [[ ! -e "$temporary" ]] || fail "temporary release path already exists: $temporary"
+    mkdir -p "$temporary"
+    chmod 700 "$temporary"
+    log "Installing exact zl-code@${version} without changing production"
+    "$NPM_BIN" install --prefix "$temporary" --omit=dev --no-audit --no-fund \
+      --package-lock=false "zl-code@${version}"
+    mv "$temporary" "$directory"
+  fi
+
+  verify_release "$version"
+  if [[ "${ZL_CODE_NPM_SERVICE_SKIP_SIGNATURE_AUDIT:-false}" != true ]]; then
+    log "Verifying npm registry signatures and attestations"
+    "$NPM_BIN" audit signatures --prefix "$directory"
+  fi
+  if [[ "${ZL_CODE_NPM_SERVICE_SKIP_PTY_SMOKE:-false}" != true ]]; then
+    log "Verifying the installed native PTY"
+    "$NODE_BIN" --input-type=module - "$directory" <<'NODE'
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const root = process.argv[2];
+const pty = require(`${root}/node_modules/node-pty`);
+await new Promise((resolve, reject) => {
+  const child = pty.spawn("/bin/sh", ["-lc", "printf zl-code-pty-ok"], {
+    cols: 80,
+    rows: 24,
+    cwd: root,
+    env: process.env,
+  });
+  let output = "";
+  child.onData((chunk) => {
+    output += chunk;
+  });
+  child.onExit(({ exitCode }) => {
+    if (exitCode === 0 && output.includes("zl-code-pty-ok")) resolve();
+    else reject(new Error(`PTY smoke failed with exit ${exitCode}: ${output}`));
+  });
+});
+NODE
+  fi
+
+  atomic_symlink "$directory" "$RUNTIME_ROOT/candidate"
+  echo "candidate=$(readlink -f "$RUNTIME_ROOT/candidate")"
+  if [[ -e "$RUNTIME_ROOT/current" || -L "$RUNTIME_ROOT/current" ]]; then
+    echo "current=$(readlink -f "$RUNTIME_ROOT/current")"
+  else
+    echo "current=absent"
+  fi
+  echo "cutover=not-performed"
+}
+
+sqlite_quick_check() {
+  local database_path=$1
+  "$NODE_BIN" - "$database_path" <<'NODE'
+const { DatabaseSync } = require("node:sqlite");
+const database = new DatabaseSync(process.argv[2], { readOnly: true });
+const rows = database.prepare("PRAGMA quick_check").all();
+database.close();
+if (rows.length !== 1 || rows[0].quick_check !== "ok") {
+  console.error(JSON.stringify(rows));
+  process.exit(1);
+}
+console.log("quick_check=ok");
+NODE
+}
+
+create_backup() {
+  local source_database="${PRODUCTION_HOME}/userdata/state.sqlite"
+  local timestamp
+  local destination
+  local boundary_archive
+  acquire_lock
+  require_executable "$NODE_BIN"
+  require_file "$source_database"
+  require_file "$PRODUCTION_HOME/userdata/environment-id"
+  require_file "$PRODUCTION_HOME/userdata/server-runtime.json"
+  require_command sha256sum
+  require_command tar
+
+  timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
+  destination="${OPERATOR_STATE}/backups/${timestamp}"
+  boundary_archive="${destination}/runtime-boundary.tar"
+  mkdir -p "$destination"
+  chmod 700 "$destination"
+
+  log "Creating an online SQLite backup"
+  "$NODE_BIN" --input-type=module - "$source_database" "$destination/state.sqlite" <<'NODE'
+import { DatabaseSync, backup } from "node:sqlite";
+const source = new DatabaseSync(process.argv[2], { readOnly: true });
+try {
+  await backup(source, process.argv[3]);
+} finally {
+  source.close();
+}
+NODE
+  sqlite_quick_check "$destination/state.sqlite"
+
+  log "Archiving the bounded configuration and identity boundary"
+  tar --create --file "$boundary_archive" --directory "$PRODUCTION_HOME" \
+    userdata/config userdata/secrets userdata/environment-id userdata/server-runtime.json
+  chmod 600 "$destination/state.sqlite" "$boundary_archive"
+  if [[ -e "$UNIT_PATH" || -L "$UNIT_PATH" ]]; then
+    cp -L "$UNIT_PATH" "$destination/zl-code-server.service.before-cutover"
+    chmod 600 "$destination/zl-code-server.service.before-cutover"
+  fi
+  sha256sum "$destination/state.sqlite" "$boundary_archive" >"$destination/SHA256SUMS"
+  chmod 600 "$destination/SHA256SUMS"
+  {
+    echo "created_at=$timestamp"
+    echo "source_home=$PRODUCTION_HOME"
+    echo "sqlite_backup=state.sqlite"
+    echo "boundary_archive=runtime-boundary.tar"
+    echo "quick_check=ok"
+  } >"$destination/manifest"
+  chmod 600 "$destination/manifest"
+  echo "backup_dir=$destination"
+}
+
+save_git_rollback_unit() {
+  mkdir -p "$ROLLBACK_DIR/git"
+  chmod 700 "$ROLLBACK_DIR" "$ROLLBACK_DIR/git"
+  if [[ ! -f "$ROLLBACK_DIR/git/zl-code-server.service" ]]; then
+    [[ -e "$UNIT_PATH" || -L "$UNIT_PATH" ]] || fail "current service unit is missing: $UNIT_PATH"
+    cp -L "$UNIT_PATH" "$ROLLBACK_DIR/git/zl-code-server.service"
+    chmod 600 "$ROLLBACK_DIR/git/zl-code-server.service"
+    if [[ -L "$UNIT_PATH" ]]; then
+      readlink "$UNIT_PATH" >"$ROLLBACK_DIR/git/symlink-target"
+    fi
+  fi
+}
+
+capture_current_pointer() {
+  rm -f "$ROLLBACK_DIR/pre-activation-current-target" "$ROLLBACK_DIR/pre-activation-current-absent"
+  if [[ -e "$RUNTIME_ROOT/current" || -L "$RUNTIME_ROOT/current" ]]; then
+    readlink -f "$RUNTIME_ROOT/current" >"$ROLLBACK_DIR/pre-activation-current-target"
+  else
+    : >"$ROLLBACK_DIR/pre-activation-current-absent"
+  fi
+}
+
+capture_activation_boundary() {
+  rm -rf "$TRANSACTION_DIR"
+  mkdir -p "$TRANSACTION_DIR"
+  chmod 700 "$TRANSACTION_DIR"
+  [[ -e "$UNIT_PATH" || -L "$UNIT_PATH" ]] || fail "current service unit is missing: $UNIT_PATH"
+  cp -L "$UNIT_PATH" "$TRANSACTION_DIR/zl-code-server.service"
+  chmod 600 "$TRANSACTION_DIR/zl-code-server.service"
+  if [[ -L "$UNIT_PATH" ]]; then
+    readlink "$UNIT_PATH" >"$TRANSACTION_DIR/unit-symlink-target"
+  fi
+  if [[ -e "$RUNTIME_ROOT/current" || -L "$RUNTIME_ROOT/current" ]]; then
+    readlink -f "$RUNTIME_ROOT/current" >"$TRANSACTION_DIR/current-target"
+  else
+    : >"$TRANSACTION_DIR/current-absent"
+  fi
+  ACTIVATION_BOUNDARY_CAPTURED=true
+}
+
+install_npm_unit() {
+  local temporary="${UNIT_PATH}.tmp.$$"
+  require_file "$UNIT_TEMPLATE"
+  mkdir -p "$(dirname "$UNIT_PATH")"
+  install -m 600 "$UNIT_TEMPLATE" "$temporary"
+  mv -Tf "$temporary" "$UNIT_PATH"
+}
+
+restore_git_unit_and_pointer() {
+  local temporary="${UNIT_PATH}.rollback.$$"
+  require_file "$ROLLBACK_DIR/git/zl-code-server.service"
+  if [[ -f "$ROLLBACK_DIR/git/symlink-target" ]]; then
+    rm -f "$temporary"
+    ln -s "$(cat "$ROLLBACK_DIR/git/symlink-target")" "$temporary"
+  else
+    install -m 600 "$ROLLBACK_DIR/git/zl-code-server.service" "$temporary"
+  fi
+  mv -Tf "$temporary" "$UNIT_PATH"
+
+  if [[ -f "$ROLLBACK_DIR/pre-activation-current-target" ]]; then
+    atomic_symlink "$(cat "$ROLLBACK_DIR/pre-activation-current-target")" "$RUNTIME_ROOT/current"
+  elif [[ -f "$ROLLBACK_DIR/pre-activation-current-absent" ]]; then
+    rm -f "$RUNTIME_ROOT/current"
+  fi
+}
+
+restore_activation_boundary() {
+  local temporary="${UNIT_PATH}.rollback.$$"
+  require_file "$TRANSACTION_DIR/zl-code-server.service"
+  if [[ -f "$TRANSACTION_DIR/unit-symlink-target" ]]; then
+    rm -f "$temporary"
+    ln -s "$(cat "$TRANSACTION_DIR/unit-symlink-target")" "$temporary"
+  else
+    install -m 600 "$TRANSACTION_DIR/zl-code-server.service" "$temporary"
+  fi
+  mv -Tf "$temporary" "$UNIT_PATH"
+
+  if [[ -f "$TRANSACTION_DIR/current-target" ]]; then
+    atomic_symlink "$(cat "$TRANSACTION_DIR/current-target")" "$RUNTIME_ROOT/current"
+  elif [[ -f "$TRANSACTION_DIR/current-absent" ]]; then
+    rm -f "$RUNTIME_ROOT/current"
+  fi
+}
+
+supervised_exit_cleanup() {
+  local status=$?
+  trap - EXIT TERM INT
+  if [[ "$status" -ne 0 && "$ACTIVATION_CUTOVER_STARTED" == true && "$ACTIVATION_ROLLBACK_COMPLETED" != true ]]; then
+    emit_supervisor_phase "rolling_back"
+    if [[ "$ACTIVATION_BOUNDARY_CAPTURED" == true ]]; then
+      if restore_activation_boundary &&
+        systemctl --user daemon-reload &&
+        systemctl --user restart "$SERVICE_NAME" &&
+        systemctl --user is-active --quiet "$SERVICE_NAME" &&
+        wait_for_url "$LOCAL_URL"; then
+        ACTIVATION_ROLLBACK_COMPLETED=true
+        if [[ -n "$SUPERVISED_ROLLBACK_VERSION" ]]; then
+          echo "rollback_version=$SUPERVISED_ROLLBACK_VERSION"
+        fi
+      else
+        echo "error: cleanup could not verify the preceding service runtime" >&2
+      fi
+    fi
+  fi
+  exit "$status"
+}
+
+wait_for_url() {
+  local url=$1
+  local attempts=${ZL_CODE_NPM_SERVICE_HEALTH_ATTEMPTS:-30}
+  local attempt
+  for ((attempt = 1; attempt <= attempts; attempt += 1)); do
+    if curl --fail --silent --show-error --max-time 3 --output /dev/null "$url"; then
+      echo "health=ok attempt=$attempt url=$url"
+      return 0
+    fi
+    sleep 1
+  done
+  return 1
+}
+
+verify_runtime() {
+  local version=$1
+  local current_target
+  local main_pid
+  local command_line
+  if ! (validate_version "$version"); then
+    return 1
+  fi
+  if ! (verify_release "$version"); then
+    return 1
+  fi
+  current_target="$(readlink -f "$RUNTIME_ROOT/current")"
+  [[ "$current_target" == "$(release_dir "$version")" ]] ||
+    {
+      echo "error: current pointer does not select $(release_dir "$version"): $current_target" >&2
+      return 1
+    }
+  systemctl --user is-active --quiet "$SERVICE_NAME" || {
+    echo "error: $SERVICE_NAME is not active" >&2
+    return 1
+  }
+
+  if [[ "${ZL_CODE_NPM_SERVICE_SKIP_PROCESS_CHECK:-false}" != true ]]; then
+    main_pid="$(systemctl --user show "$SERVICE_NAME" -p MainPID --value)"
+    [[ "$main_pid" =~ ^[1-9][0-9]*$ ]] || {
+      echo "error: service has no live MainPID" >&2
+      return 1
+    }
+    command_line="$(tr '\0' ' ' <"/proc/${main_pid}/cmdline")"
+    [[ "$command_line" == *"$NODE_BIN"* ]] || {
+      echo "error: service is not using pinned Node: $command_line" >&2
+      return 1
+    }
+    [[ "$command_line" == *"${RUNTIME_ROOT}/current/node_modules/zl-code/dist/bin.mjs"* ]] ||
+      {
+        echo "error: service is not using the current npm runtime: $command_line" >&2
+        return 1
+      }
+  fi
+
+  wait_for_url "$LOCAL_URL" || {
+    echo "error: local endpoint did not become healthy: $LOCAL_URL" >&2
+    return 1
+  }
+  wait_for_url "$PUBLIC_URL" || {
+    echo "error: public endpoint did not become healthy: $PUBLIC_URL" >&2
+    return 1
+  }
+  echo "version=zl-code v${version}"
+  echo "current=$current_target"
+  echo "service=active"
+}
+
+activate_release() {
+  local version=$1
+  local backup_dir=$2
+  local confirmed=$3
+  local directory
+  local restart_id
+  local restart_requested_at
+  local current_release_identity
+  local current_version
+  local target_release_identity
+  local activation_status
+  [[ "$confirmed" == true ]] || fail "activation requires --confirm-cutover"
+  validate_version "$version"
+  [[ -n "$backup_dir" ]] || fail "activation requires --backup-dir"
+  require_file "$backup_dir/manifest"
+  require_file "$backup_dir/state.sqlite"
+  require_file "$backup_dir/runtime-boundary.tar"
+  grep -Fxq "quick_check=ok" "$backup_dir/manifest" || fail "backup was not quick_check verified"
+  acquire_lock
+  require_command curl
+  require_command install
+  require_command systemctl
+  require_executable "$NODE_BIN"
+  verify_release "$version"
+  sqlite_quick_check "$backup_dir/state.sqlite"
+  directory="$(release_dir "$version")"
+  [[ "$(readlink -f "$RUNTIME_ROOT/candidate")" == "$directory" ]] ||
+    fail "candidate pointer does not select $directory"
+  current_release_identity="$(read_current_release_identity)"
+  current_version="${current_release_identity#release:}"
+  SUPERVISED_ROLLBACK_VERSION="$current_version"
+  target_release_identity="release:${version}"
+
+  save_git_rollback_unit
+  capture_current_pointer
+  capture_activation_boundary
+  if [[ -e "$RUNTIME_ROOT/current" || -L "$RUNTIME_ROOT/current" ]]; then
+    atomic_symlink "$(readlink -f "$RUNTIME_ROOT/current")" "$RUNTIME_ROOT/previous"
+  fi
+
+  restart_requested_at="$(date --iso-8601=seconds)"
+  if [[ -n "${ZL_CODE_UPDATE_OPERATION_ID:-}" ]]; then
+    validate_operation_id "$ZL_CODE_UPDATE_OPERATION_ID"
+    restart_id="$ZL_CODE_UPDATE_OPERATION_ID"
+  else
+    restart_id="$(printf '%s-%s' "$(date -u +%Y%m%dT%H%M%SZ)" "$version")"
+  fi
+  write_restart_state \
+    "$restart_id" \
+    "${SCRIPT_PATH} activate" \
+    "$current_release_identity" \
+    "$target_release_identity" \
+    "$restart_requested_at"
+  echo "restart_id=$restart_id"
+  echo "restart_state_file=$RESTART_STATE_FILE"
+  echo "current_version=$current_version"
+  echo "target_version=$version"
+  echo "validated_at=$restart_requested_at"
+
+  emit_supervisor_phase "draining"
+  log "Requesting graceful update drain"
+  ACTIVATION_CUTOVER_STARTED=true
+  systemctl --user kill --signal="$DRAIN_SIGNAL" "$SERVICE_NAME"
+  if ! await_restart_state_field "drainStartedAt" "$DRAIN_ACK_TIMEOUT_SECONDS"; then
+    restore_activation_boundary
+    systemctl --user daemon-reload
+    systemctl --user restart "$SERVICE_NAME"
+    systemctl --user is-active --quiet "$SERVICE_NAME"
+    wait_for_url "$LOCAL_URL" || fail "service did not recover after the drain acknowledgement timeout"
+    ACTIVATION_ROLLBACK_COMPLETED=true
+    echo "rollback_version=$current_version"
+    fail "service did not acknowledge update drain within ${DRAIN_ACK_TIMEOUT_SECONDS}s"
+  fi
+  echo "drain=acknowledged"
+  if await_restart_state_field "quiesceCompletedAt" "$DRAIN_QUIESCE_TIMEOUT_SECONDS"; then
+    echo "drain_quiesce=completed"
+  else
+    echo "drain_quiesce=timeout"
+  fi
+
+  set +e
+  (
+    set -Eeuo pipefail
+    emit_supervisor_phase "activating"
+    log "Activating zl-code@${version}"
+    atomic_symlink "$directory" "$RUNTIME_ROOT/current"
+    install_npm_unit
+    systemctl --user daemon-reload
+    systemctl --user restart "$SERVICE_NAME"
+    emit_supervisor_phase "verifying"
+    verify_runtime "$version"
+    patch_restart_state "{\"healthyAt\":\"$(date --iso-8601=seconds)\"}"
+  )
+  activation_status=$?
+  set -e
+
+  if [[ "$activation_status" -ne 0 ]]; then
+    emit_supervisor_phase "rolling_back"
+    echo "error: npm activation failed; restoring the immediately preceding service runtime" >&2
+    restore_activation_boundary
+    systemctl --user daemon-reload
+    systemctl --user restart "$SERVICE_NAME"
+    systemctl --user is-active --quiet "$SERVICE_NAME"
+    wait_for_url "$LOCAL_URL" || fail "activation failed and the preceding service runtime did not recover"
+    ACTIVATION_ROLLBACK_COMPLETED=true
+    echo "rollback_version=$current_version"
+    fail "activation failed and the preceding service runtime was restored"
+  fi
+  echo "backup_dir=$backup_dir"
+  echo "rollback=git-unit-retained"
+  if [[ -f "$RESTART_STATE_FILE" ]]; then
+    echo "restart_state=$(cat "$RESTART_STATE_FILE")"
+  fi
+}
+
+supervised_update() {
+  local version=$1
+  local confirmed=$2
+  local backup_dir
+  local backup_output
+  [[ "$confirmed" == true ]] || fail "supervised update requires --confirm-supervised"
+  SUPERVISED_MODE=true
+  trap supervised_exit_cleanup EXIT
+  trap 'exit 124' TERM INT
+  acquire_lock
+
+  emit_supervisor_phase "preparing"
+  prepare_release "$version" true
+  emit_supervisor_phase "backing_up"
+  backup_output="$(create_backup)"
+  printf '%s\n' "$backup_output" >&2
+  backup_dir="$(printf '%s\n' "$backup_output" | sed -n 's/^backup_dir=//p' | tail -n 1)"
+  [[ -n "$backup_dir" ]] || fail "supervised update did not produce a backup path"
+  emit_supervisor_phase "draining"
+  activate_release "$version" "$backup_dir" true
+  emit_supervisor_phase "succeeded"
+  trap - EXIT TERM INT
+}
+
+install_update_supervisor() {
+  local confirmed=$1
+  local temporary="${SUPERVISOR_UNIT_PATH}.tmp.$$"
+  [[ "$confirmed" == true ]] || fail "supervisor installation requires --confirm-install"
+  acquire_lock
+  require_command install
+  require_command systemctl
+  require_file "$SUPERVISOR_UNIT_TEMPLATE"
+  require_file "$RUNTIME_ROOT/current/node_modules/zl-code/dist/bin.mjs"
+
+  mkdir -p "$(dirname "$SUPERVISOR_UNIT_PATH")"
+  install -m 600 "$SUPERVISOR_UNIT_TEMPLATE" "$temporary"
+  mv -Tf "$temporary" "$SUPERVISOR_UNIT_PATH"
+  systemctl --user daemon-reload
+  systemctl --user enable --now "$SUPERVISOR_SERVICE_NAME"
+  systemctl --user is-active --quiet "$SUPERVISOR_SERVICE_NAME"
+  echo "supervisor_unit=$SUPERVISOR_UNIT_PATH"
+  echo "supervisor_service=active"
+}
+
+rollback_runtime() {
+  local target=$1
+  local confirmed=$2
+  local previous_target
+  [[ "$confirmed" == true ]] || fail "rollback requires --confirm-cutover"
+  [[ "$target" == previous || "$target" == git ]] || fail "rollback target must be previous or git"
+  acquire_lock
+  require_command curl
+  require_command systemctl
+
+  if [[ "$target" == git ]]; then
+    log "Restoring the retained git-backed service unit"
+    restore_git_unit_and_pointer
+    systemctl --user daemon-reload
+    systemctl --user restart "$SERVICE_NAME"
+    systemctl --user is-active --quiet "$SERVICE_NAME"
+    wait_for_url "$LOCAL_URL" || fail "git-backed service did not become healthy"
+    echo "rollback=git"
+    return
+  fi
+
+  [[ -e "$RUNTIME_ROOT/previous" || -L "$RUNTIME_ROOT/previous" ]] ||
+    fail "previous npm pointer is absent"
+  previous_target="$(readlink -f "$RUNTIME_ROOT/previous")"
+  [[ -d "$previous_target" ]] || fail "previous npm release is missing: $previous_target"
+  atomic_symlink "$previous_target" "$RUNTIME_ROOT/current"
+  systemctl --user restart "$SERVICE_NAME"
+  systemctl --user is-active --quiet "$SERVICE_NAME"
+  wait_for_url "$LOCAL_URL" || fail "previous npm release did not become healthy"
+  echo "rollback=previous"
+  echo "current=$previous_target"
+}
+
+show_status() {
+  echo "service=$SERVICE_NAME"
+  systemctl --user show "$SERVICE_NAME" -p ActiveState -p SubState -p MainPID -p FragmentPath -p WorkingDirectory --no-pager
+  for pointer in candidate current previous; do
+    if [[ -e "$RUNTIME_ROOT/$pointer" || -L "$RUNTIME_ROOT/$pointer" ]]; then
+      echo "$pointer=$(readlink -f "$RUNTIME_ROOT/$pointer")"
+    else
+      echo "$pointer=absent"
+    fi
+  done
+  echo "unit=$(readlink -f "$UNIT_PATH")"
+  echo "node=$($NODE_BIN --version)"
+}
+
+command_name=${1:-}
+shift || true
+case "$command_name" in
+  status)
+    [[ $# -eq 0 ]] || fail "status accepts no arguments"
+    show_status
+    ;;
+  prepare)
+    version=${1:-}
+    shift || true
+    no_cutover=false
+    [[ ${1:-} == --no-cutover ]] && no_cutover=true && shift
+    [[ $# -eq 0 ]] || fail "unexpected prepare arguments: $*"
+    prepare_release "$version" "$no_cutover"
+    ;;
+  backup)
+    [[ $# -eq 0 ]] || fail "backup accepts no arguments"
+    create_backup
+    ;;
+  activate)
+    version=${1:-}
+    shift || true
+    backup_dir=""
+    confirmed=false
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --backup-dir)
+          [[ $# -ge 2 ]] || fail "--backup-dir requires a path"
+          backup_dir=$2
+          shift 2
+          ;;
+        --confirm-cutover)
+          confirmed=true
+          shift
+          ;;
+        *) fail "unexpected activate argument: $1" ;;
+      esac
+    done
+    activate_release "$version" "$backup_dir" "$confirmed"
+    ;;
+  verify)
+    version=${1:-}
+    shift || true
+    [[ $# -eq 0 ]] || fail "verify accepts exactly one version"
+    verify_runtime "$version"
+    ;;
+  rollback)
+    target=""
+    confirmed=false
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --to)
+          [[ $# -ge 2 ]] || fail "--to requires previous or git"
+          target=$2
+          shift 2
+          ;;
+        --confirm-cutover)
+          confirmed=true
+          shift
+          ;;
+        *) fail "unexpected rollback argument: $1" ;;
+      esac
+    done
+    rollback_runtime "$target" "$confirmed"
+    ;;
+  supervised-update)
+    version=${1:-}
+    confirmation=${2:-}
+    [[ $# -eq 2 ]] || fail "supervised-update requires <version> --confirm-supervised"
+    [[ "$confirmation" == "--confirm-supervised" ]] || fail "supervised update requires --confirm-supervised"
+    supervised_update "$version" true
+    ;;
+  install-supervisor)
+    confirmation=${1:-}
+    [[ $# -eq 1 ]] || fail "install-supervisor requires --confirm-install"
+    [[ "$confirmation" == "--confirm-install" ]] || fail "supervisor installation requires --confirm-install"
+    install_update_supervisor true
+    ;;
+  help | --help | -h)
+    usage
+    ;;
+  *)
+    usage >&2
+    exit 2
+    ;;
+esac