install-openclaw.sh

#!/usr/bin/env bash
set -euo pipefail
trap 'echo "Installer failed near line ${LINENO}: ${BASH_COMMAND}" >&2' ERR

NOOSPHERE_HOME="${NOOSPHERE_HOME:-$HOME/.noosphere}"
NOOSPHERE_INSTALL_OPENCLAW="${NOOSPHERE_INSTALL_OPENCLAW:-true}"
NOOSPHERE_SHOW_CREDENTIALS="${NOOSPHERE_SHOW_CREDENTIALS:-false}"
NOOSPHERE_CREDENTIALS_FILE="${NOOSPHERE_CREDENTIALS_FILE:-$NOOSPHERE_HOME/credentials.json}"
NOOSPHERE_PORT="${NOOSPHERE_PORT:-}"
if [[ -n ${NOOSPHERE_VERSION:-} ]]; then
  NOOSPHERE_VERSION_WAS_EXPLICIT=1
else
  NOOSPHERE_VERSION_WAS_EXPLICIT=0
fi
if [[ -n ${NOOSPHERE_IMAGE:-} ]]; then
  NOOSPHERE_IMAGE_WAS_EXPLICIT=1
else
  NOOSPHERE_IMAGE_WAS_EXPLICIT=0
fi
NOOSPHERE_VERSION="${NOOSPHERE_VERSION:-}"
NOOSPHERE_IMAGE="${NOOSPHERE_IMAGE:-}"
APP_URL="${APP_URL:-}"
BIND_ADDRESS="${BIND_ADDRESS:-}"
REDIS_URL="${REDIS_URL:-}"
PG_POOL_MAX="${PG_POOL_MAX:-}"
PG_IDLE_TIMEOUT_MS="${PG_IDLE_TIMEOUT_MS:-}"
PG_CONN_TIMEOUT_MS="${PG_CONN_TIMEOUT_MS:-}"
NOOSPHERE_ADMIN_PASSWORD_RESET="${NOOSPHERE_ADMIN_PASSWORD_RESET:-}"
NOOSPHERE_FORCE_ADMIN="${NOOSPHERE_FORCE_ADMIN:-}"
NOOSPHERE_BOOTSTRAP_SECRETS_FILE="${NOOSPHERE_BOOTSTRAP_SECRETS_FILE:-}"
NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE="${NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE:-}"
NOOSPHERE_HYBRID_PROVIDER_CONFIG_JSON="${NOOSPHERE_HYBRID_PROVIDER_CONFIG_JSON:-}"
NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64="${NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64:-}"
if [[ -v NOOSPHERE_HYBRID_RETRIEVAL_ENABLED ]]; then
  NOOSPHERE_HYBRID_RETRIEVAL_ENABLED_WAS_SET=1
else
  NOOSPHERE_HYBRID_RETRIEVAL_ENABLED_WAS_SET=0
fi
NOOSPHERE_HYBRID_RETRIEVAL_ENABLED="${NOOSPHERE_HYBRID_RETRIEVAL_ENABLED-}"
NOOSPHERE_HYBRID_QUERY_PROFILE_ID="${NOOSPHERE_HYBRID_QUERY_PROFILE_ID:-}"
NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION="${NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION:-}"
NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_JSON="${NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_JSON:-}"
NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64="${NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64:-}"
NOOSPHERE_HYBRID_WORKER_CONCURRENCY="${NOOSPHERE_HYBRID_WORKER_CONCURRENCY:-}"
NOOSPHERE_HYBRID_LEASE_SECONDS="${NOOSPHERE_HYBRID_LEASE_SECONDS:-}"
NOOSPHERE_HYBRID_MAX_ATTEMPTS="${NOOSPHERE_HYBRID_MAX_ATTEMPTS:-}"
NOOSPHERE_HYBRID_WORKER_POLL_MS="${NOOSPHERE_HYBRID_WORKER_POLL_MS:-}"
NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS="${NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS:-}"
NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES="${NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES:-}"
NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH="${NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH:-}"
NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH="${NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH:-}"
NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS="${NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS:-}"
NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS="${NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS:-}"
PLUGIN_SPEC="${NOOSPHERE_PLUGIN_SPEC:-npm:@sweetsophia/openclaw-noosphere-memory@1.13.3}"
SECRETS_DIR="${OPENCLAW_SECRETS_DIR:-$HOME/.openclaw/secrets}"
SECRETS_FILE="${NOOSPHERE_SECRETS_FILE:-$SECRETS_DIR/noosphere-memory.json}"
SECRET_PROVIDER_ID="${NOOSPHERE_SECRET_PROVIDER_ID:-noosphere-memory}"
PLUGIN_ID="noosphere-memory"
POSTGRES_CONTROLLER_SCRIPT_SHA256='996c7a96b4b3be91db3754d7fdef92a00f7943340316b124e6932abc505770aa'
POSTGRES_CONTROLLER_SCRIPT_URL='https://raw.githubusercontent.com/SweetSophia/noosphere/9da4af0a7b2275aa91eecd102095e0e470bbb0e3/scripts/run-pgvector-transition-controller.sh'
POSTGRES_SWITCH_SCRIPT_SHA256='aa364a1d3344905972d87d02c1c0b6954558b4fbd610474a02ebf730861fb479'
POSTGRES_SWITCH_SCRIPT_URL='https://raw.githubusercontent.com/SweetSophia/noosphere/9da4af0a7b2275aa91eecd102095e0e470bbb0e3/scripts/switch-pgvector-compose.sh'
POSTGRES_VERIFY_SCRIPT_SHA256='1f17bf84739a5d9d2c4c25b456d72a2e987b1a5ede3b22370e817160fb850134'
POSTGRES_VERIFY_SCRIPT_URL='https://raw.githubusercontent.com/SweetSophia/noosphere/9da4af0a7b2275aa91eecd102095e0e470bbb0e3/scripts/verify-deploy.sh'
EXPLICIT_POSTGRES_PASSWORD="${POSTGRES_PASSWORD:-}"
EXPLICIT_POSTGRES_MIGRATION_PASSWORD="${POSTGRES_MIGRATION_PASSWORD:-}"
EXPLICIT_POSTGRES_APP_PASSWORD="${POSTGRES_APP_PASSWORD:-}"
EXPLICIT_POSTGRES_HYBRID_ADMIN_PASSWORD="${POSTGRES_HYBRID_ADMIN_PASSWORD:-}"
EXPLICIT_POSTGRES_HYBRID_WORKER_PASSWORD="${POSTGRES_HYBRID_WORKER_PASSWORD:-}"
EXPLICIT_NEXTAUTH_SECRET="${NEXTAUTH_SECRET:-}"
EXPLICIT_ADMIN_PASSWORD="${NOOSPHERE_ADMIN_PASSWORD:-}"
EXPLICIT_API_KEY="${NOOSPHERE_BOOTSTRAP_API_KEY:-}"

need() {
  if ! command -v "$1" >/dev/null 2>&1; then
    echo "Missing required command: $1" >&2
    exit 1
  fi
}

run_openclaw() {
  env \
    -u POSTGRES_PASSWORD \
    -u POSTGRES_MIGRATION_PASSWORD \
    -u POSTGRES_APP_PASSWORD \
    -u POSTGRES_HYBRID_ADMIN_PASSWORD \
    -u POSTGRES_HYBRID_WORKER_PASSWORD \
    -u NEXTAUTH_SECRET \
    -u REDIS_URL \
    -u NOOSPHERE_ADMIN_PASSWORD \
    -u NOOSPHERE_BOOTSTRAP_API_KEY \
    -u NOOSPHERE_HYBRID_PROVIDER_CONFIG_JSON \
    -u NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64 \
    -u NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_JSON \
    -u NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64 \
    openclaw "$@"
}

random_secret() {
  node -e "console.log(require('crypto').randomBytes(Number(process.argv[1])).toString('base64url'))" "$1"
}

json_get() {
  local file="$1"
  local key="$2"
  JSON_GET_FILE="$file" JSON_GET_KEY="$key" node -e 'try { const fs=require("fs"); const p=process.env.JSON_GET_FILE; const k=process.env.JSON_GET_KEY; if (!p || !k || !fs.existsSync(p)) process.exit(0); const data=JSON.parse(fs.readFileSync(p,"utf8")); if (typeof data[k] === "string") process.stdout.write(data[k]); } catch { process.exit(0); }'
}

assert_no_symlink_path_components() {
  local target=$1 label=$2
  TARGET_PATH="$target" TARGET_LABEL="$label" node -e '
    const fs = require("node:fs");
    const path = require("node:path");
    let current = path.resolve(process.env.TARGET_PATH);
    while (true) {
      try {
        if (fs.lstatSync(current).isSymbolicLink()) {
          throw new Error(`Refusing symlinked ${process.env.TARGET_LABEL} path component: ${current}`);
        }
      } catch (error) {
        if (error.code !== "ENOENT") throw error;
      }
      const parent = path.dirname(current);
      if (parent === current) break;
      current = parent;
    }
  '
}

write_credentials_json() {
  local target=$1 include_runtime=${2:-false} include_bootstrap=${3:-true} parent temp
  parent=$(dirname "$target")
  assert_no_symlink_path_components "$target" credential || return 1
  install -d -m 700 "$parent"
  assert_no_symlink_path_components "$target" credential || return 1
  [[ ! -L "$target" ]] || {
    echo "Refusing symlinked credential target: $target" >&2
    return 1
  }
  temp=$(mktemp "$parent/.credentials.XXXXXX")
  CREDENTIALS_EXISTING_TARGET="$target" \
  CREDENTIALS_BASE_URL="$APP_URL" \
  CREDENTIALS_API_KEY="$INTEGRATION_API_KEY" \
  CREDENTIALS_BOOTSTRAP_API_KEY="$API_KEY" \
  CREDENTIALS_ADMIN_PASSWORD="$ADMIN_PASSWORD" \
  CREDENTIALS_POSTGRES_PASSWORD="$POSTGRES_PASSWORD" \
  CREDENTIALS_POSTGRES_MIGRATION_PASSWORD="$POSTGRES_MIGRATION_PASSWORD" \
  CREDENTIALS_POSTGRES_APP_PASSWORD="$POSTGRES_APP_PASSWORD" \
  CREDENTIALS_POSTGRES_HYBRID_ADMIN_PASSWORD="$POSTGRES_HYBRID_ADMIN_PASSWORD" \
  CREDENTIALS_POSTGRES_HYBRID_WORKER_PASSWORD="$POSTGRES_HYBRID_WORKER_PASSWORD" \
  CREDENTIALS_NEXTAUTH_SECRET="$NEXTAUTH_SECRET" \
  CREDENTIALS_INCLUDE_RUNTIME="$include_runtime" \
  CREDENTIALS_INCLUDE_BOOTSTRAP="$include_bootstrap" \
    node -e '
      const fs = require("node:fs");
      const target = process.argv[1];
      let integrationApiKeys = {};
      const existingTarget = process.env.CREDENTIALS_EXISTING_TARGET;
      if (existingTarget && fs.existsSync(existingTarget)) {
        const existing = JSON.parse(fs.readFileSync(existingTarget, "utf8"));
        if (existing.integrationApiKeys && typeof existing.integrationApiKeys === "object" && !Array.isArray(existing.integrationApiKeys)) {
          integrationApiKeys = Object.fromEntries(Object.entries(existing.integrationApiKeys).filter(
            ([name, key]) => /^[a-z0-9-]+$/.test(name) && typeof key === "string" && /^noo_[A-Za-z0-9_-]+$/.test(key),
          ));
        }
      }
      const data = {
        baseUrl: process.env.CREDENTIALS_BASE_URL,
        apiKey: process.env.CREDENTIALS_API_KEY,
        integrationApiKeys,
        adminEmail: "admin@noosphere.local",
        adminPassword: process.env.CREDENTIALS_ADMIN_PASSWORD,
      };
      if (process.env.CREDENTIALS_INCLUDE_BOOTSTRAP === "true") {
        data.bootstrapApiKey = process.env.CREDENTIALS_BOOTSTRAP_API_KEY;
      }
      if (process.env.CREDENTIALS_INCLUDE_RUNTIME === "true") {
        Object.assign(data, {
          postgresPassword: process.env.CREDENTIALS_POSTGRES_PASSWORD,
          postgresMigrationPassword: process.env.CREDENTIALS_POSTGRES_MIGRATION_PASSWORD,
          postgresAppPassword: process.env.CREDENTIALS_POSTGRES_APP_PASSWORD,
          postgresHybridAdminPassword: process.env.CREDENTIALS_POSTGRES_HYBRID_ADMIN_PASSWORD,
          postgresHybridWorkerPassword: process.env.CREDENTIALS_POSTGRES_HYBRID_WORKER_PASSWORD,
          nextAuthSecret: process.env.CREDENTIALS_NEXTAUTH_SECRET,
        });
      }
      fs.writeFileSync(target, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
    ' "$temp"
  chmod 600 "$temp"
  assert_no_symlink_path_components "$target" credential || return 1
  mv "$temp" "$target"
}

validated_local_app_url() {
  APP_URL_INPUT=$1 EXPECTED_PORT=$NOOSPHERE_PORT node -e '
    const os = require("node:os");
    const input = process.env.APP_URL_INPUT;
    const expectedPort = String(process.env.EXPECTED_PORT || "");
    const url = new URL(input);
    const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
    const local = new Set(["localhost", "127.0.0.1", "::1"]);
    for (const entries of Object.values(os.networkInterfaces())) {
      for (const entry of entries || []) local.add(String(entry.address).toLowerCase());
    }
    if (url.protocol !== "http:" || url.username || url.password ||
        url.pathname !== "/" || url.search || url.hash || !url.port ||
        url.port !== expectedPort || !local.has(host)) {
      throw new Error("Noosphere application URL is not the expected local endpoint");
    }
    process.stdout.write(url.origin);
  '
}

local_no_proxy_curl() {
  curl --disable --noproxy '*' --connect-timeout 5 --max-time 15 "$@"
}

api_http_status_with_key() {
  local key=$1 endpoint=$2 config status base_url
  [[ "$key" =~ ^noo_[A-Za-z0-9_-]+$ ]] || {
    printf '000'
    return 0
  }
  base_url=$(validated_local_app_url "$APP_URL") || {
    printf '000'
    return 0
  }
  config=$(mktemp)
  chmod 600 "$config"
  printf 'silent\nshow-error\nheader = "Authorization: Bearer %s"\n' "$key" > "$config"
  status=$(local_no_proxy_curl --config "$config" --output /dev/null --write-out '%{http_code}' \
    "$base_url$endpoint" 2>/dev/null || true)
  rm -f "$config"
  printf '%s' "${status:-000}"
}

api_write_probe_status_with_key() {
  local key=$1 config body status base_url
  [[ "$key" =~ ^noo_[A-Za-z0-9_-]+$ ]] || { printf '000'; return 0; }
  base_url=$(validated_local_app_url "$APP_URL") || { printf '000'; return 0; }
  config=$(mktemp)
  body=$(mktemp)
  chmod 600 "$config" "$body"
  printf 'silent\nshow-error\nheader = "Authorization: Bearer %s"\n' "$key" > "$config"
  printf '{}\n' > "$body"
  status=$(local_no_proxy_curl --config "$config" --request POST --header 'Content-Type: application/json' \
    --data-binary "@$body" --output /dev/null --write-out '%{http_code}' \
    "$base_url/api/articles" 2>/dev/null || true)
  rm -f "$config" "$body"
  printf '%s' "${status:-000}"
}

integration_key_is_safe() {
  local key=$1 write_status admin_status
  [[ -n "$key" ]] || return 1
  write_status=$(api_write_probe_status_with_key "$key")
  admin_status=$(api_http_status_with_key "$key" '/api/keys')
  if [[ "$write_status" == 000 || "$admin_status" == 000 ]]; then
    return 2
  fi
  [[ "$write_status" == 400 && "$admin_status" == 403 ]]
}

create_scoped_integration_key() {
  local label=$1 config body response name raw base_url
  [[ "$API_KEY" =~ ^noo_[A-Za-z0-9_-]+$ ]] || {
    echo 'Bootstrap API key has an unexpected format.' >&2
    return 1
  }
  name="guided-${label}-$(date +%s)-${RANDOM}"
  base_url=$(validated_local_app_url "$APP_URL") || {
    echo 'Refusing to send the bootstrap API key to a non-local Noosphere URL.' >&2
    return 1
  }
  config=$(mktemp)
  body=$(mktemp)
  response=$(mktemp)
  chmod 600 "$config" "$body" "$response"
  printf 'silent\nshow-error\nfail-with-body\nheader = "Authorization: Bearer %s"\n' "$API_KEY" > "$config"
  printf '{"name":"%s","permissions":"WRITE","allowedScopes":[]}\n' "$name" > "$body"
  if ! local_no_proxy_curl --config "$config" --request POST --header 'Content-Type: application/json' \
    --data-binary "@$body" --output "$response" "$base_url/api/keys"; then
    rm -f "$config" "$body" "$response"
    echo "Failed to create a scoped ${label} API key." >&2
    return 1
  fi
  raw=$(json_get "$response" key)
  rm -f "$config" "$body" "$response"
  [[ "$raw" =~ ^noo_[A-Za-z0-9_-]+$ ]] || {
    echo "Noosphere returned an invalid scoped ${label} API key." >&2
    return 1
  }
  printf '%s' "$raw"
}

select_scoped_integration_key() {
  local existing=$1 label=$2 status
  if integration_key_is_safe "$existing"; then
    printf '%s' "$existing"
    return 0
  else
    status=$?
  fi
  if [[ "$status" == 2 ]]; then
    echo "Could not verify the existing scoped ${label} API key; refusing to rotate it after a transport failure." >&2
    return 1
  fi
  create_scoped_integration_key "$label"
}

env_get() {
  local file="$1"
  local key="$2"
  if [ ! -f "$file" ]; then
    return 0
  fi
  awk -v key="$key" '
    {
      sub(/\r$/, "")
      eq = index($0, "=")
      if (eq > 1 && substr($0, 1, eq - 1) == key) {
        print substr($0, eq + 1)
        exit
      }
    }
  ' "$file"
}

env_has_key() {
  local file="$1"
  local key="$2"
  if [ ! -f "$file" ]; then
    return 1
  fi
  awk -v key="$key" '
    {
      sub(/\r$/, "")
      eq = index($0, "=")
      if (eq > 1 && substr($0, 1, eq - 1) == key) {
        found = 1
        exit
      }
    }
    END { exit found ? 0 : 1 }
  ' "$file"
}

is_placeholder_secret() {
  case "$1" in
    ""|CHANGE_ME*|replace-with-*|noo_replace_with_*) return 0 ;;
    *) return 1 ;;
  esac
}

env_get_secret() {
  local value
  value="$(env_get "$1" "$2")"
  if is_placeholder_secret "$value"; then
    return 0
  fi
  printf '%s' "$value"
}

reject_multiline_env_value() {
  local label=$1 value=$2
  if [[ "$value" == *$'\n'* || "$value" == *$'\r'* ]]; then
    echo "$label must not contain CR or LF characters." >&2
    exit 1
  fi
}

normalize_hybrid_provider_config() {
  if [[ -n "$NOOSPHERE_HYBRID_PROVIDER_CONFIG_JSON" && -n "$NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64" ]]; then
    echo 'Set only one of NOOSPHERE_HYBRID_PROVIDER_CONFIG_JSON or NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64.' >&2
    exit 1
  fi
  if [[ -z "$NOOSPHERE_HYBRID_PROVIDER_CONFIG_JSON" && -z "$NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64" ]]; then
    NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64="$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64)"
  fi
  if [[ -z "$NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64" ]]; then
    NOOSPHERE_HYBRID_PROVIDER_CONFIG_JSON="${NOOSPHERE_HYBRID_PROVIDER_CONFIG_JSON:-[]}"
    NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64="$(
      printf '%s' "$NOOSPHERE_HYBRID_PROVIDER_CONFIG_JSON" |
        node -e 'let value=""; process.stdin.setEncoding("utf8"); process.stdin.on("data", chunk => value += chunk); process.stdin.on("end", () => { const parsed=JSON.parse(value); if (!Array.isArray(parsed) || parsed.length > 100) throw new Error("provider configuration must be an array of at most 100 entries"); process.stdout.write(Buffer.from(value, "utf8").toString("base64")); });'
    )"
  fi
  printf '%s' "$NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64" |
    node -e 'let value=""; process.stdin.setEncoding("utf8"); process.stdin.on("data", chunk => value += chunk); process.stdin.on("end", () => { if (value.length > 174764 || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) throw new Error("provider configuration must be canonical base64"); const bytes=Buffer.from(value, "base64"); if (bytes.toString("base64") !== value) throw new Error("provider configuration must be canonical base64"); const parsed=JSON.parse(bytes.toString("utf8")); if (!Array.isArray(parsed) || parsed.length > 100) throw new Error("provider configuration must be an array of at most 100 entries"); });'
}

normalize_hybrid_retrieval_config() {
  if [[ "$NOOSPHERE_HYBRID_RETRIEVAL_ENABLED" != false && "$NOOSPHERE_HYBRID_RETRIEVAL_ENABLED" != true ]]; then
    echo 'NOOSPHERE_HYBRID_RETRIEVAL_ENABLED must be exactly true or false.' >&2
    exit 1
  fi
  if [[ -n "$NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_JSON" && -n "$NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64" ]]; then
    echo 'Set only one of NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_JSON or NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64.' >&2
    exit 1
  fi
  if [[ -z "$NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_JSON" && -z "$NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64" ]]; then
    NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64="$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64)"
  fi
  if [[ -n "$NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_JSON" ]]; then
    NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64="$(
      printf '%s' "$NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_JSON" |
        node -e 'let size=0; const chunks=[]; process.stdin.on("data", chunk => { size += chunk.length; if (size > 8192) { console.error("hybrid cache keyring JSON exceeds 8192 bytes"); process.exit(1); } chunks.push(chunk); }); process.stdin.on("end", () => { const bytes=Buffer.concat(chunks); const value=bytes.toString("utf8"); if (!Buffer.from(value, "utf8").equals(bytes)) throw new Error("hybrid cache keyring JSON must be valid UTF-8"); JSON.parse(value); process.stdout.write(bytes.toString("base64")); });'
    )"
  fi
  if [[ "$NOOSPHERE_HYBRID_RETRIEVAL_ENABLED" == true && ! "$NOOSPHERE_HYBRID_QUERY_PROFILE_ID" =~ ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$ ]]; then
    echo 'NOOSPHERE_HYBRID_QUERY_PROFILE_ID must be a UUID when Phase C is enabled.' >&2
    exit 1
  fi
  HYBRID_CACHE_ENABLED="$NOOSPHERE_HYBRID_RETRIEVAL_ENABLED" \
  HYBRID_CACHE_ACTIVE_VERSION="$NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION" \
  HYBRID_CACHE_KEYRING_B64="$NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64" \
    node -e '
      const enabled = process.env.HYBRID_CACHE_ENABLED === "true";
      const active = process.env.HYBRID_CACHE_ACTIVE_VERSION || "";
      const encoded = process.env.HYBRID_CACHE_KEYRING_B64 || "";
      if (!encoded) {
        if (enabled || active) throw new Error("hybrid cache active version and keyring must be configured together");
        process.exit(0);
      }
      if (encoded.length > 8192 || encoded.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) throw new Error("hybrid cache keyring must use canonical base64");
      const bytes = Buffer.from(encoded, "base64");
      if (bytes.toString("base64") !== encoded) throw new Error("hybrid cache keyring must use canonical base64");
      const parsed = JSON.parse(bytes.toString("utf8"));
      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("hybrid cache keyring must be an object");
      const entries = Object.entries(parsed);
      if (entries.length < 1 || entries.length > 3) throw new Error("hybrid cache keyring must contain one to three keys");
      for (const [version, value] of entries) {
        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/.test(version) || typeof value !== "string") throw new Error("hybrid cache keyring entry is invalid");
        const key = Buffer.from(value, "base64");
        if (key.toString("base64") !== value || key.length < 32 || key.length > 64) throw new Error("hybrid cache keys must be canonical base64 for 32-64 bytes");
      }
      if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/.test(active) || !Object.hasOwn(parsed, active)) throw new Error("active hybrid cache key version is absent");
    '
}

# This mode exercises the real installer guard without performing installation
# side effects. It is used by the repository policy gate.
if [[ "${NOOSPHERE_INSTALLER_TEST_MODE:-}" == runtime-env-validation ]]; then
  reject_multiline_env_value TEST_VALUE "${NOOSPHERE_INSTALLER_TEST_VALUE:-}"
  exit 0
fi
if [[ "${NOOSPHERE_INSTALLER_TEST_MODE:-}" == hybrid-provider-config-validation ]]; then
  normalize_hybrid_provider_config
  printf '%s\n' "$NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64"
  exit 0
fi
if [[ "${NOOSPHERE_INSTALLER_TEST_MODE:-}" == hybrid-retrieval-config-validation ]]; then
  if [[ "$NOOSPHERE_HYBRID_RETRIEVAL_ENABLED_WAS_SET" == 0 ]]; then
    NOOSPHERE_HYBRID_RETRIEVAL_ENABLED=false
  fi
  normalize_hybrid_retrieval_config
  printf '%s\n' "$NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64"
  exit 0
fi

write_runtime_env() {
  local env_tmp
  env_tmp="$(mktemp "$NOOSPHERE_HOME/.env.XXXXXX")" || {
    echo "Failed to create temporary file for runtime .env" >&2
    exit 1
  }
  cat > "$env_tmp" <<ENV
NOOSPHERE_VERSION=${NOOSPHERE_VERSION}
NOOSPHERE_IMAGE=${NOOSPHERE_IMAGE}
NOOSPHERE_PORT=${NOOSPHERE_PORT}
APP_URL=${APP_URL}
BIND_ADDRESS=${BIND_ADDRESS}
POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
POSTGRES_MIGRATION_PASSWORD=${POSTGRES_MIGRATION_PASSWORD}
POSTGRES_APP_PASSWORD=${POSTGRES_APP_PASSWORD}
POSTGRES_HYBRID_ADMIN_PASSWORD=${POSTGRES_HYBRID_ADMIN_PASSWORD}
POSTGRES_HYBRID_WORKER_PASSWORD=${POSTGRES_HYBRID_WORKER_PASSWORD}
NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
NOOSPHERE_ADMIN_PASSWORD=${ADMIN_PASSWORD}
NOOSPHERE_ADMIN_PASSWORD_RESET=${NOOSPHERE_ADMIN_PASSWORD_RESET:-false}
NOOSPHERE_FORCE_ADMIN=${NOOSPHERE_FORCE_ADMIN:-false}
NOOSPHERE_BOOTSTRAP_API_KEY=${API_KEY}
NOOSPHERE_BOOTSTRAP_SECRETS_FILE=${NOOSPHERE_BOOTSTRAP_SECRETS_FILE:-/tmp/noosphere-bootstrap-secrets/secrets.json}
REDIS_URL=${REDIS_URL}
PG_POOL_MAX=${PG_POOL_MAX}
PG_IDLE_TIMEOUT_MS=${PG_IDLE_TIMEOUT_MS}
PG_CONN_TIMEOUT_MS=${PG_CONN_TIMEOUT_MS}
NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE=${NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE}
NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64=${NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64}
NOOSPHERE_HYBRID_RETRIEVAL_ENABLED=${NOOSPHERE_HYBRID_RETRIEVAL_ENABLED}
NOOSPHERE_HYBRID_QUERY_PROFILE_ID=${NOOSPHERE_HYBRID_QUERY_PROFILE_ID}
NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION=${NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION}
NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64=${NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64}
NOOSPHERE_HYBRID_WORKER_CONCURRENCY=${NOOSPHERE_HYBRID_WORKER_CONCURRENCY}
NOOSPHERE_HYBRID_LEASE_SECONDS=${NOOSPHERE_HYBRID_LEASE_SECONDS}
NOOSPHERE_HYBRID_MAX_ATTEMPTS=${NOOSPHERE_HYBRID_MAX_ATTEMPTS}
NOOSPHERE_HYBRID_WORKER_POLL_MS=${NOOSPHERE_HYBRID_WORKER_POLL_MS}
NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS=${NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS}
NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES=${NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES}
NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH=${NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH}
NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH=${NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH}
NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS=${NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS}
NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS=${NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS}
ENV
  chmod 600 "$env_tmp"
  mv "$env_tmp" "$NOOSPHERE_HOME/.env"
}

ensure_runtime_env_secret() {
  local key=$1 value=$2 current temp
  current="$(env_get_secret "$NOOSPHERE_HOME/.env" "$key")"
  [[ "$current" != "$value" ]] || return 0
  temp="$(mktemp "$NOOSPHERE_HOME/.env.XXXXXX")"
  # Rewrite through Node so an existing final line without LF cannot merge
  # with the appended credential. Passing the value through the environment
  # also avoids embedding operator-supplied secrets in generated source text.
  ENV_REWRITE_FILE="$NOOSPHERE_HOME/.env" \
    ENV_REWRITE_KEY="$key" \
    ENV_REWRITE_VALUE="$value" \
    node -e '
      const fs = require("node:fs");
      const file = process.env.ENV_REWRITE_FILE;
      const key = process.env.ENV_REWRITE_KEY;
      const value = process.env.ENV_REWRITE_VALUE;
      if (!file || !key || value === undefined) process.exit(1);
      if (/[\r\n]/.test(value)) {
        console.error(`${key} must not contain CR or LF characters.`);
        process.exit(1);
      }
      const retained = fs.readFileSync(file, "utf8")
        .split(/\r?\n/)
        .filter((line) => {
          const separator = line.indexOf("=");
          return !(separator > 0 && line.slice(0, separator) === key);
        });
      while (retained.at(-1) === "") retained.pop();
      retained.push(`${key}=${value}`);
      process.stdout.write(`${retained.join("\n")}\n`);
    ' > "$temp"
  chmod 600 "$temp"
  mv "$temp" "$NOOSPHERE_HOME/.env"
}

resolve_runtime_config() {
  local runtime_env="$NOOSPHERE_HOME/.env"

  NOOSPHERE_PORT="${NOOSPHERE_PORT:-$(env_get "$runtime_env" NOOSPHERE_PORT)}"
  NOOSPHERE_PORT="${NOOSPHERE_PORT:-6578}"
  NOOSPHERE_VERSION="${NOOSPHERE_VERSION:-$(env_get "$runtime_env" NOOSPHERE_VERSION)}"
  NOOSPHERE_VERSION="${NOOSPHERE_VERSION:-1.13.3}"
  if ((NOOSPHERE_VERSION_WAS_EXPLICIT == 1 && NOOSPHERE_IMAGE_WAS_EXPLICIT == 0)); then
    # A version-bound public upgrade must not inherit an installer-persisted
    # image from the previous release. Operators retaining a custom registry or
    # image must pass NOOSPHERE_IMAGE explicitly alongside the release version.
    NOOSPHERE_IMAGE=''
  else
    NOOSPHERE_IMAGE="${NOOSPHERE_IMAGE:-$(env_get "$runtime_env" NOOSPHERE_IMAGE)}"
  fi
  APP_URL="${APP_URL:-$(env_get "$runtime_env" APP_URL)}"
  BIND_ADDRESS="${BIND_ADDRESS:-$(env_get "$runtime_env" BIND_ADDRESS)}"
  REDIS_URL="${REDIS_URL:-$(env_get "$runtime_env" REDIS_URL)}"
  REDIS_URL="${REDIS_URL:-redis://redis:6379}"
  PG_POOL_MAX="${PG_POOL_MAX:-$(env_get "$runtime_env" PG_POOL_MAX)}"
  PG_POOL_MAX="${PG_POOL_MAX:-20}"
  PG_IDLE_TIMEOUT_MS="${PG_IDLE_TIMEOUT_MS:-$(env_get "$runtime_env" PG_IDLE_TIMEOUT_MS)}"
  PG_IDLE_TIMEOUT_MS="${PG_IDLE_TIMEOUT_MS:-30000}"
  PG_CONN_TIMEOUT_MS="${PG_CONN_TIMEOUT_MS:-$(env_get "$runtime_env" PG_CONN_TIMEOUT_MS)}"
  PG_CONN_TIMEOUT_MS="${PG_CONN_TIMEOUT_MS:-5000}"
  NOOSPHERE_ADMIN_PASSWORD_RESET="${NOOSPHERE_ADMIN_PASSWORD_RESET:-$(env_get "$runtime_env" NOOSPHERE_ADMIN_PASSWORD_RESET)}"
  NOOSPHERE_ADMIN_PASSWORD_RESET="${NOOSPHERE_ADMIN_PASSWORD_RESET:-false}"
  NOOSPHERE_FORCE_ADMIN="${NOOSPHERE_FORCE_ADMIN:-$(env_get "$runtime_env" NOOSPHERE_FORCE_ADMIN)}"
  NOOSPHERE_FORCE_ADMIN="${NOOSPHERE_FORCE_ADMIN:-false}"
  NOOSPHERE_BOOTSTRAP_SECRETS_FILE="${NOOSPHERE_BOOTSTRAP_SECRETS_FILE:-$(env_get "$runtime_env" NOOSPHERE_BOOTSTRAP_SECRETS_FILE)}"
  NOOSPHERE_BOOTSTRAP_SECRETS_FILE="${NOOSPHERE_BOOTSTRAP_SECRETS_FILE:-/tmp/noosphere-bootstrap-secrets/secrets.json}"
  NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE="${NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE:-$(env_get "$runtime_env" NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE)}"
  NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE="${NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE:-120}"
  NOOSPHERE_IMAGE="${NOOSPHERE_IMAGE:-ghcr.io/sweetsophia/noosphere:${NOOSPHERE_VERSION}}"
}

prepare_guard_script() {
  local relative_source=$1 url=$2 expected_sha=$3 target=$4 source='' temp actual_sha installer_dir
  installer_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
  if [[ -f "$installer_dir/$relative_source" ]]; then
    source="$installer_dir/$relative_source"
  fi

  temp=$(mktemp "$NOOSPHERE_HOME/.guard-script.XXXXXX")
  if [[ -n "$source" ]]; then
    install -m 600 "$source" "$temp"
  else
    curl -fsSL "$url" -o "$temp"
    chmod 600 "$temp"
  fi
  actual_sha=$(sha256sum "$temp" | awk '{print $1}')
  if [[ "$actual_sha" != "$expected_sha" ]]; then
    rm -f "$temp"
    echo "Refusing PostgreSQL guard script with unexpected checksum: $relative_source" >&2
    exit 1
  fi
  install -m 700 "$temp" "$target"
  rm -f "$temp"
}

fsync_installer_path() {
  node -e '
    const fs = require("node:fs");
    const fd = fs.openSync(process.argv[1], "r");
    try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
  ' "$1"
}

assert_installer_owned_regular_file() {
  local path=$1 mode
  [[ -f "$path" && ! -L "$path" ]] || {
    echo "Installer artifact is missing, non-regular, or a symlink: $path" >&2
    return 1
  }
  [[ $(stat -c '%u' "$path") == "$(id -u)" ]] || {
    echo "Installer artifact has an unexpected owner: $path" >&2
    return 1
  }
  mode=$(stat -c '%a' "$path")
  (( (8#$mode & 8#022) == 0 )) || {
    echo "Installer artifact permits group/world writes: $path" >&2
    return 1
  }
}

resolve_local_docker_endpoint() {
  local docker_context docker_host docker_socket
  if [[ -n ${DOCKER_CONTEXT:-} ]]; then
    docker_context=$DOCKER_CONTEXT
    docker_host=$(docker context inspect "$docker_context" --format '{{(index .Endpoints "docker").Host}}') || {
      echo "Could not inspect Docker context $docker_context" >&2
      return 1
    }
  elif [[ -n ${DOCKER_HOST:-} ]]; then
    docker_host=$DOCKER_HOST
  else
    docker_context=$(docker context show) || {
      echo 'Could not determine the active Docker context.' >&2
      return 1
    }
    docker_host=$(docker context inspect "$docker_context" --format '{{(index .Endpoints "docker").Host}}') || {
      echo "Could not inspect Docker context $docker_context" >&2
      return 1
    }
  fi
  [[ "$docker_host" == unix://* ]] || {
    echo "Refusing non-local Docker endpoint: $docker_host" >&2
    return 1
  }
  docker_socket=${docker_host#unix://}
  [[ "$docker_socket" == /* ]] || {
    echo "Docker Unix endpoint must use an absolute path: $docker_host" >&2
    return 1
  }
  printf 'unix://%s\n' "$(realpath -m "$docker_socket")"
}

prepare_postgres_controller_runtime() {
  local config_temp
  POSTGRES_CONTROLLER_ROOT="$NOOSPHERE_HOME/postgres-transition-controller"
  POSTGRES_CONTROLLER_HOME="$POSTGRES_CONTROLLER_ROOT/home"
  POSTGRES_CONTROLLER_MANIFEST="$POSTGRES_CONTROLLER_ROOT/manifest.json"
  POSTGRES_CONTROLLER_STATE="$POSTGRES_CONTROLLER_ROOT/state.json"
  POSTGRES_CONTROLLER_CANDIDATE="$POSTGRES_CONTROLLER_ROOT/candidate-compose.yml"
  POSTGRES_CONTROLLER_SOURCE="$POSTGRES_CONTROLLER_ROOT/source-compose.yml"
  POSTGRES_CONTROLLER_SCRIPT="$POSTGRES_CONTROLLER_ROOT/run-pgvector-transition-controller.sh"
  POSTGRES_SWITCH_SCRIPT="$POSTGRES_CONTROLLER_ROOT/switch-pgvector-compose.sh"
  POSTGRES_VERIFY_SCRIPT="$POSTGRES_CONTROLLER_ROOT/verify-deploy.sh"
  export POSTGRES_CONTROLLER_ROOT POSTGRES_CONTROLLER_HOME POSTGRES_CONTROLLER_MANIFEST
  export POSTGRES_CONTROLLER_STATE POSTGRES_CONTROLLER_CANDIDATE POSTGRES_CONTROLLER_SOURCE
  export POSTGRES_CONTROLLER_SCRIPT POSTGRES_SWITCH_SCRIPT POSTGRES_VERIFY_SCRIPT

  install -d -m 700 "$NOOSPHERE_HOME" "$POSTGRES_CONTROLLER_ROOT" \
    "$POSTGRES_CONTROLLER_HOME" "$POSTGRES_CONTROLLER_HOME/docker" "$POSTGRES_BACKUP_DIR"
  prepare_guard_script scripts/run-pgvector-transition-controller.sh \
    "$POSTGRES_CONTROLLER_SCRIPT_URL" "$POSTGRES_CONTROLLER_SCRIPT_SHA256" \
    "$POSTGRES_CONTROLLER_SCRIPT"
  prepare_guard_script scripts/switch-pgvector-compose.sh \
    "$POSTGRES_SWITCH_SCRIPT_URL" "$POSTGRES_SWITCH_SCRIPT_SHA256" \
    "$POSTGRES_SWITCH_SCRIPT"
  prepare_guard_script scripts/verify-deploy.sh \
    "$POSTGRES_VERIFY_SCRIPT_URL" "$POSTGRES_VERIFY_SCRIPT_SHA256" \
    "$POSTGRES_VERIFY_SCRIPT"
  fsync_installer_path "$POSTGRES_CONTROLLER_SCRIPT"
  fsync_installer_path "$POSTGRES_SWITCH_SCRIPT"
  fsync_installer_path "$POSTGRES_VERIFY_SCRIPT"

  config_temp=$(mktemp "$POSTGRES_CONTROLLER_ROOT/.docker-config.XXXXXX")
  printf '{}\n' > "$config_temp"
  chmod 0600 "$config_temp"
  fsync_installer_path "$config_temp"
  install -m 600 "$config_temp" "$POSTGRES_CONTROLLER_HOME/docker/config.json"
  rm -f "$config_temp"
  fsync_installer_path "$POSTGRES_CONTROLLER_HOME/docker/config.json"
  fsync_installer_path "$POSTGRES_CONTROLLER_HOME/docker"
  fsync_installer_path "$POSTGRES_CONTROLLER_HOME"
  fsync_installer_path "$POSTGRES_CONTROLLER_ROOT"
}

sanitize_postgres_controller_environment() {
  local docker_host=$1 fixed_path=$2 controller_home=$3 ambient_name
  while IFS= read -r ambient_name; do
    case "$ambient_name" in
      DOCKER_*|COMPOSE_*) unset "$ambient_name" ;;
    esac
  done < <(compgen -v)
  unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY http_proxy https_proxy all_proxy no_proxy
  unset BASH_ENV ENV CDPATH GLOBIGNORE
  unset NOOSPHERE_A2B_LOCK_FD NOOSPHERE_A2B_LOCK_PATH
  unset NOOSPHERE_CONTROLLER_FIXTURE_ROOT
  unset NOOSPHERE_CONTROLLER_TEST_INTERRUPT_AFTER_INTENT
  unset NOOSPHERE_CONTROLLER_TEST_SIGNAL_AFTER_GUARD_SPAWN
  unset NOOSPHERE_CONTROLLER_TEST_FAIL_EVIDENCE
  unset NOOSPHERE_CONTROLLER_TEST_SIGNAL_AFTER_AUTHORIZATION
  unset NOOSPHERE_CONTROLLER_TEST_SIGNAL_BEFORE_COMPLETE
  unset NOOSPHERE_CONTROLLER_TEST_SIGNAL_BEFORE_GUARD
  export HOME=$controller_home
  export DOCKER_CONFIG="$controller_home/docker"
  export DOCKER_HOST=$docker_host
  export COMPOSE_DISABLE_ENV_FILE=1
  export PATH=$fixed_path
}

postgres_controller_compose_version_signature() (
  local docker_host=$1 docker_path=$2 fixed_path=$3 controller_home=$4
  sanitize_postgres_controller_environment "$docker_host" "$fixed_path" "$controller_home"
  "$docker_path" compose version --short | sha256sum | awk '{print $1}'
)

postgres_controller_compose_model_signature() (
  local docker_host=$1 docker_path=$2 candidate=$3 env_file=$4
  local fixed_path=$5 controller_home=$6
  sanitize_postgres_controller_environment "$docker_host" "$fixed_path" "$controller_home"
  "$docker_path" compose --project-directory "$NOOSPHERE_HOME" \
    --env-file "$env_file" -f "$candidate" config --no-interpolate |
    sha256sum | awk '{print $1}'
)

postgres_controller_verification_url() {
  local host=${BIND_ADDRESS:-127.0.0.1}
  [[ "$host" != 0.0.0.0 ]] || host=127.0.0.1
  is_valid_ipv4 "$host" || {
    echo "Controller verification requires an IPv4 bind address, found: $host" >&2
    return 1
  }
  printf 'http://%s:%s\n' "$host" "$NOOSPHERE_PORT"
}

assert_postgres_controller_bootstrap_node() {
  local bootstrap_path='/usr/sbin:/usr/bin:/sbin:/bin' node_path node_mode
  node_path=$(PATH="$bootstrap_path" command -v node 2>/dev/null || true)
  [[ -n "$node_path" ]] || {
    echo 'Existing-volume upgrade requires Node on the controller bootstrap PATH (/usr/sbin:/usr/bin:/sbin:/bin).' >&2
    echo 'Install the distribution Node package, then rerun the same checksum-pinned installer command.' >&2
    return 1
  }
  node_path=$(realpath "$node_path")
  [[ -f "$node_path" && ! -L "$node_path" && $(stat -c '%u' "$node_path") == 0 ]] || {
    echo "Controller bootstrap Node is not a root-owned regular file: $node_path" >&2
    return 1
  }
  node_mode=$(stat -c '%a' "$node_path")
  (( (8#$node_mode & 8#022) == 0 )) || {
    echo "Controller bootstrap Node permits group/world writes: $node_path" >&2
    return 1
  }
  PATH="$bootstrap_path" node -e 'process.exit(0)'
}

write_postgres_controller_manifest() {
  local docker_path docker_host engine_id plugin_path platform fixed_path lock_root
  local compose_version_sha effective_compose_sha manifest_temp app_url config_file
  local bound_input
  for bound_input in \
    "$POSTGRES_CONTROLLER_SCRIPT" \
    "$POSTGRES_SWITCH_SCRIPT" \
    "$POSTGRES_VERIFY_SCRIPT" \
    "$POSTGRES_CONTROLLER_SOURCE" \
    "$POSTGRES_CONTROLLER_CANDIDATE" \
    "$NOOSPHERE_HOME/.env" \
    "$POSTGRES_CONTROLLER_HOME/docker/config.json"; do
    assert_installer_owned_regular_file "$bound_input"
    fsync_installer_path "$bound_input"
  done
  fsync_installer_path "$NOOSPHERE_HOME"
  fsync_installer_path "$POSTGRES_CONTROLLER_HOME/docker"
  fsync_installer_path "$POSTGRES_CONTROLLER_ROOT"
  docker_path=$(realpath "$(command -v docker)")
  docker_host=$(resolve_local_docker_endpoint)
  config_file="$POSTGRES_CONTROLLER_HOME/docker/config.json"
  engine_id=$(DOCKER_CONFIG="$POSTGRES_CONTROLLER_HOME/docker" DOCKER_HOST="$docker_host" \
    "$docker_path" info --format '{{.ID}}')
  [[ -n "$engine_id" ]] || {
    echo 'Could not determine the Docker engine ID for controller preparation.' >&2
    return 1
  }
  platform=$(DOCKER_CONFIG="$POSTGRES_CONTROLLER_HOME/docker" DOCKER_HOST="$docker_host" \
    "$docker_path" info --format '{{.OSType}}/{{.Architecture}}')
  case "$platform" in
    linux/x86_64) platform=linux/amd64 ;;
    linux/aarch64) platform=linux/arm64 ;;
    linux/amd64|linux/arm64) ;;
    *) echo "Unsupported Docker engine platform for controller execution: $platform" >&2; return 1 ;;
  esac
  plugin_path=$(DOCKER_HOST="$docker_host" \
    "$docker_path" info --format '{{json .ClientInfo.Plugins}}' |
    jq -er '[.[] | select(.Name == "compose") | .Path] | if length == 1 then .[0] else error("Compose plugin identity is ambiguous") end')
  plugin_path=$(realpath "$plugin_path")
  [[ -f "$plugin_path" && -x "$plugin_path" && ! -L "$plugin_path" ]] || {
    echo "Docker Compose plugin is unavailable or unsafe: $plugin_path" >&2
    return 1
  }
  fixed_path='/usr/sbin:/usr/bin:/sbin:/bin'
  compose_version_sha=$(postgres_controller_compose_version_signature \
    "$docker_host" "$docker_path" "$fixed_path" "$POSTGRES_CONTROLLER_HOME")
  effective_compose_sha=$(postgres_controller_compose_model_signature \
    "$docker_host" "$docker_path" "$POSTGRES_CONTROLLER_CANDIDATE" \
    "$NOOSPHERE_HOME/.env" "$fixed_path" "$POSTGRES_CONTROLLER_HOME")
  lock_root=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}
  app_url=$(postgres_controller_verification_url)
  manifest_temp=$(mktemp "$POSTGRES_CONTROLLER_ROOT/.manifest.XXXXXX")
  trap 'rm -f "$manifest_temp"' RETURN
  jq -n \
    --arg engineId "$engine_id" \
    --arg dockerEndpoint "$docker_host" \
    --arg liveCompose "$NOOSPHERE_HOME/docker-compose.yml" \
    --arg sourceSnapshot "$POSTGRES_CONTROLLER_SOURCE" \
    --arg sourceSnapshotSha256 "$(sha256sum "$POSTGRES_CONTROLLER_SOURCE" | awk '{print $1}')" \
    --arg candidateCompose "$POSTGRES_CONTROLLER_CANDIDATE" \
    --arg candidateComposeSha256 "$(sha256sum "$POSTGRES_CONTROLLER_CANDIDATE" | awk '{print $1}')" \
    --arg envFile "$NOOSPHERE_HOME/.env" \
    --arg envFileSha256 "$(sha256sum "$NOOSPHERE_HOME/.env" | awk '{print $1}')" \
    --arg controllerPath "$POSTGRES_CONTROLLER_SCRIPT" \
    --arg controllerSha256 "$POSTGRES_CONTROLLER_SCRIPT_SHA256" \
    --arg guard "$POSTGRES_SWITCH_SCRIPT" \
    --arg guardSha256 "$POSTGRES_SWITCH_SCRIPT_SHA256" \
    --arg verifier "$POSTGRES_VERIFY_SCRIPT" \
    --arg verifierSha256 "$POSTGRES_VERIFY_SCRIPT_SHA256" \
    --arg dockerPath "$docker_path" \
    --arg dockerSha256 "$(sha256sum "$docker_path" | awk '{print $1}')" \
    --arg dockerComposeVersionSha256 "$compose_version_sha" \
    --arg composePluginPath "$plugin_path" \
    --arg composePluginSha256 "$(sha256sum "$plugin_path" | awk '{print $1}')" \
    --arg dockerConfigSha256 "$(sha256sum "$config_file" | awk '{print $1}')" \
    --arg effectiveComposeSha256 "$effective_compose_sha" \
    --arg backupDir "$POSTGRES_BACKUP_DIR" \
    --arg lockRoot "$lock_root" \
    --arg controllerHome "$POSTGRES_CONTROLLER_HOME" \
    --arg fixedPath "$fixed_path" \
    --arg platform "$platform" \
    --arg appUrl "$app_url" \
    --arg guardJournal "$POSTGRES_BACKUP_DIR/noosphere_postgres_data.phase-a2b.json" '
      {
        version:1, phase:"prepared", engineId:$engineId,
        dockerEndpoint:$dockerEndpoint, volume:"noosphere_postgres_data",
        liveCompose:$liveCompose, sourceSnapshot:$sourceSnapshot,
        sourceSnapshotSha256:$sourceSnapshotSha256,
        candidateCompose:$candidateCompose,
        candidateComposeSha256:$candidateComposeSha256,
        envFile:$envFile, envFileSha256:$envFileSha256,
        guard:$guard, guardSha256:$guardSha256,
        controllerPath:$controllerPath, controllerSha256:$controllerSha256,
        guardArgs:[
          "--compose-file",$liveCompose,
          "--env-file",$envFile,
          "--db-container","noosphere-openclaw-db",
          "--app-container","noosphere-openclaw-app",
          "--volume","noosphere_postgres_data",
          "--authorization-volume","noosphere_postgres_authorization",
          "--backup-dir",$backupDir,
          "--platform",$platform,
          "--defer-app-restart"
        ],
        verifier:$verifier, verifierSha256:$verifierSha256,
        dockerPath:$dockerPath, dockerSha256:$dockerSha256,
        dockerComposeVersionSha256:$dockerComposeVersionSha256,
        composePluginPath:$composePluginPath,
        composePluginSha256:$composePluginSha256,
        dockerConfigSha256:$dockerConfigSha256,
        effectiveComposeSha256:$effectiveComposeSha256,
        backupDir:$backupDir, lockRoot:$lockRoot,
        controllerHome:$controllerHome, fixedPath:$fixedPath,
        dbContainer:"noosphere-openclaw-db",
        appContainer:"noosphere-openclaw-app",
        authorizationVolume:"noosphere_postgres_authorization",
        platform:$platform, appUrl:$appUrl,
        guardJournal:$guardJournal
      }
    ' > "$manifest_temp"
  chmod 0600 "$manifest_temp"
  fsync_installer_path "$manifest_temp"
  install -m 600 "$manifest_temp" "$POSTGRES_CONTROLLER_MANIFEST"
  fsync_installer_path "$POSTGRES_CONTROLLER_MANIFEST"
  fsync_installer_path "$POSTGRES_CONTROLLER_ROOT"
  rm -f "$manifest_temp"
  trap - RETURN
}

release_postgres_operation_lock() {
  local fd=${NOOSPHERE_A2B_LOCK_FD:-}
  if [[ -n "$fd" ]]; then
    [[ "$fd" =~ ^[0-9]+$ ]] || {
      echo 'PostgreSQL operation lock descriptor is malformed.' >&2
      return 1
    }
    eval "exec ${fd}>&-"
  fi
  unset NOOSPHERE_A2B_LOCK_FD NOOSPHERE_A2B_LOCK_PATH
}

ensure_persistent_user_manager() {
  local runtime_dir uid
  need systemd-run
  need systemctl
  need loginctl
  uid=$(id -u)
  if [[ $(loginctl show-user "$uid" -p Linger --value 2>/dev/null || true) != yes ]]; then
    if command -v sudo >/dev/null 2>&1; then
      sudo loginctl enable-linger "$USER"
    else
      loginctl enable-linger "$USER"
    fi
  fi
  [[ $(loginctl show-user "$uid" -p Linger --value 2>/dev/null || true) == yes ]] || {
    echo "Persistent user manager is required. Run: sudo loginctl enable-linger $USER" >&2
    return 1
  }

  runtime_dir=${XDG_RUNTIME_DIR:-/run/user/$uid}
  if [[ -S "$runtime_dir/bus" ]]; then
    export XDG_RUNTIME_DIR="$runtime_dir"
    export DBUS_SESSION_BUS_ADDRESS="unix:path=$runtime_dir/bus"
  fi
  if ! systemctl --user show-environment >/dev/null 2>&1 && command -v sudo >/dev/null 2>&1; then
    sudo systemctl start "user@$uid.service"
    export XDG_RUNTIME_DIR="$runtime_dir"
    export DBUS_SESSION_BUS_ADDRESS="unix:path=$runtime_dir/bus"
  fi
  systemctl --user show-environment >/dev/null 2>&1 || {
    echo "The persistent user manager is not reachable for $USER." >&2
    echo "Start user@$uid.service, then rerun the same checksum-pinned installer command." >&2
    return 1
  }
}

run_existing_postgres_controller_transition() {
  local phase unit_base unit unit_load_state systemd_status=0 property
  local -a systemd_args=()
  release_postgres_operation_lock
  if [[ ! -e "$POSTGRES_CONTROLLER_STATE" ]]; then
    "$POSTGRES_CONTROLLER_SCRIPT" --prepare \
      --manifest "$POSTGRES_CONTROLLER_MANIFEST" \
      --state "$POSTGRES_CONTROLLER_STATE"
  fi
  phase=$(jq -er '.phase' "$POSTGRES_CONTROLLER_STATE")
  [[ "$phase" != complete ]] || return 0
  [[ "$phase" != incident ]] || {
    echo "PostgreSQL transition is in terminal incident state: $POSTGRES_CONTROLLER_STATE" >&2
    return 1
  }

  ensure_persistent_user_manager
  unit_base="noosphere-pgvector-transition-$(date -u +%Y%m%dT%H%M%S)-$$"
  unit="$unit_base.service"
  unit_load_state=$(systemctl --user show "$unit" -p LoadState --value) || {
    echo "Could not query transient controller unit state: $unit" >&2
    return 1
  }
  if [[ "$unit_load_state" != not-found ]]; then
    echo "Refusing existing transient controller unit: $unit" >&2
    return 1
  fi
  systemd_args=(
    systemd-run --user --unit="$unit_base" --wait --collect --quiet
    --setenv="CONTROLLER_UNIT=$unit"
  )
  if [[ -n ${XDG_STATE_HOME:-} ]]; then
    systemd_args+=(--setenv="XDG_STATE_HOME=$XDG_STATE_HOME")
  fi
  while IFS= read -r property; do
    systemd_args+=(--property="$property")
  done < <(bash -p -c 'source "$1"; systemd_properties "$2"' \
    _ "$POSTGRES_CONTROLLER_SCRIPT" "$NOOSPHERE_HOME")
  systemd_args+=("$POSTGRES_CONTROLLER_SCRIPT" --execute --state "$POSTGRES_CONTROLLER_STATE")
  "${systemd_args[@]}" || systemd_status=$?
  ((systemd_status == 0)) || return "$systemd_status"
  phase=$(jq -er '.phase' "$POSTGRES_CONTROLLER_STATE")
  [[ "$phase" == complete ]] || {
    echo "PostgreSQL transition controller exited without complete state: $phase" >&2
    return 1
  }
}

provision_existing_postgres_roles_for_controller() {
  local docker_host=$1 docker_path=$2 provision_log provision_exit=0 db_network role_env
  db_network=$(DOCKER_HOST="$docker_host" "$docker_path" inspect noosphere-openclaw-db |
    jq -er '
      .[0].NetworkSettings.Networks
      | to_entries
      | map(select((.value.Aliases // []) | index("db")))
      | if length == 1 then .[0].key else error("database Compose network is ambiguous") end
    ') || {
    echo 'Could not identify the existing PostgreSQL Compose network for role provisioning.' >&2
    return 1
  }
  role_env=$(mktemp)
  provision_log=$(mktemp) || {
    rm -f "$role_env"
    return 1
  }
  chmod 0600 "$role_env" "$provision_log"
  printf '%s\n' \
    "NOOSPHERE_BOOTSTRAP_DATABASE_URL=postgresql://noosphere:${POSTGRES_PASSWORD}@db:5432/noosphere" \
    "DATABASE_URL=postgresql://noosphere_migrator:${POSTGRES_MIGRATION_PASSWORD}@db:5432/noosphere" \
    "NOOSPHERE_APP_DATABASE_URL=postgresql://noosphere_app:${POSTGRES_APP_PASSWORD}@db:5432/noosphere" \
    > "$role_env"
  DOCKER_HOST="$docker_host" "$docker_path" run --rm --pull never \
    --network "$db_network" \
    --env-file "$role_env" \
    --entrypoint node \
    "$NOOSPHERE_IMAGE" docker/provision-database-roles.mjs \
    < /dev/null >"$provision_log" 2>&1 || provision_exit=$?
  if ((provision_exit != 0)); then
    echo "Database role provisioning for the existing PostgreSQL transition failed with exit code $provision_exit:" >&2
    cat "$provision_log" >&2
    rm -f "$role_env" "$provision_log"
    return "$provision_exit"
  fi
  cat "$provision_log"
  rm -f "$role_env" "$provision_log"
}

route_postgres_install_transition() {
  local docker_host docker_path
  if [[ "$existing_switch_required" == true ]]; then
    assert_postgres_controller_bootstrap_node
    docker_host=$(resolve_local_docker_endpoint)
    docker_path=$(realpath "$(command -v docker)")
    DOCKER_HOST="$docker_host" "$docker_path" compose \
      --project-directory "$NOOSPHERE_HOME" \
      --env-file "$NOOSPHERE_HOME/.env" \
      -f "$POSTGRES_CONTROLLER_CANDIDATE" pull
    provision_existing_postgres_roles_for_controller "$docker_host" "$docker_path"
    write_postgres_controller_manifest
    run_existing_postgres_controller_transition
    reacquire_postgres_operation_lock_from_manifest || return 1
    controller_transition_completed=true
    return 0
  fi

  if [[ "$new_install_required" == true ]]; then
    "$POSTGRES_SWITCH_SCRIPT" --prepare-new-install \
      --compose-file "$NOOSPHERE_HOME/docker-compose.yml" \
      --env-file "$NOOSPHERE_HOME/.env" \
      --db-container noosphere-openclaw-db \
      --app-container noosphere-openclaw-app \
      --backup-dir "$POSTGRES_BACKUP_DIR"
  fi
}

reconcile_postgres_controller_before_configuration() {
  local controller_phase guard_evidence expected_guard_evidence expected_guard_sha actual_guard_sha
  [[ -e "$POSTGRES_CONTROLLER_STATE" ]] || return 0
  assert_installer_owned_regular_file "$POSTGRES_CONTROLLER_STATE" || return 1
  controller_phase=$(jq -er '.phase' "$POSTGRES_CONTROLLER_STATE") || return 1
  case "$controller_phase" in
    complete)
      guard_evidence="$POSTGRES_BACKUP_DIR/noosphere_postgres_data.phase-a2b.json"
      jq -e '
        (.guardJournalEvidence.path | type == "string" and startswith("/")) and
        (.guardJournalEvidence.sha256 | type == "string" and test("^[a-f0-9]{64}$")) and
        .guardJournalEvidence.phase == "complete"
      ' "$POSTGRES_CONTROLLER_STATE" >/dev/null 2>&1 || {
        echo 'Controller state is complete but its durable guard-journal binding is malformed.' >&2
        echo "Controller state: $POSTGRES_CONTROLLER_STATE" >&2
        return 1
      }
      expected_guard_evidence=$(jq -er '.guardJournalEvidence.path' "$POSTGRES_CONTROLLER_STATE")
      expected_guard_sha=$(jq -er '.guardJournalEvidence.sha256' "$POSTGRES_CONTROLLER_STATE")
      [[ $(realpath -m "$expected_guard_evidence") == "$(realpath -m "$guard_evidence")" ]] &&
        assert_installer_owned_regular_file "$guard_evidence" >/dev/null 2>&1 &&
        actual_guard_sha=$(sha256sum "$guard_evidence" | awk '{print $1}') &&
        [[ "$actual_guard_sha" == "$expected_guard_sha" ]] &&
        jq -e '.mode == "switch" and .phase == "complete"' "$guard_evidence" >/dev/null 2>&1 || {
        echo 'Controller state is complete but durable switch closure evidence is missing or incomplete.' >&2
        echo "Controller state: $POSTGRES_CONTROLLER_STATE" >&2
        echo "Guard evidence: $guard_evidence" >&2
        return 1
      }
      reacquire_postgres_operation_lock_from_manifest || return 1
      controller_transition_completed=true
      ;;
    incident)
      echo "PostgreSQL transition is in terminal incident state: $POSTGRES_CONTROLLER_STATE" >&2
      return 1
      ;;
    *)
      echo "Resuming PostgreSQL transition controller state: $controller_phase"
      assert_postgres_controller_bootstrap_node || return 1
      run_existing_postgres_controller_transition || return 1
      reacquire_postgres_operation_lock_from_manifest || return 1
      controller_transition_completed=true
      ;;
  esac
}

acquire_postgres_operation_lock() {
  local expected_docker_host=${1:-} expected_engine_id=${2:-} expected_lock_root=${3:-}
  local docker_host engine_id ambient_lock_root lock_root lock_key lock_path
  docker_host=$(resolve_local_docker_endpoint) || return 1
  [[ -z "$expected_docker_host" || "$docker_host" == "$expected_docker_host" ]] || {
    echo 'Docker endpoint changed while the PostgreSQL transition controller was active.' >&2
    return 1
  }
  ambient_lock_root=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}
  lock_root=$ambient_lock_root
  if [[ -n "$expected_lock_root" ]]; then
    [[ "$expected_lock_root" == /* ]] || {
      echo 'Manifest runtime lock directory is not absolute.' >&2
      return 1
    }
    [[ $(realpath -m "$ambient_lock_root") == "$(realpath -m "$expected_lock_root")" ]] || {
      echo 'Runtime lock directory changed while the PostgreSQL transition controller was active.' >&2
      return 1
    }
    lock_root=$expected_lock_root
  fi
  [[ "$lock_root" == /* && -d "$lock_root" && ! -L "$lock_root" ]] || {
    echo "Runtime lock directory is unavailable or unsafe: $lock_root" >&2
    return 1
  }
  [[ $(stat -c '%u' "$lock_root") == "$(id -u)" ]] || {
    echo 'Runtime lock directory is not owned by the current user.' >&2
    return 1
  }
  engine_id=$(DOCKER_HOST="$docker_host" docker info --format '{{.ID}}') || {
    echo 'Could not determine the Docker engine ID.' >&2
    return 1
  }
  [[ -n "$engine_id" ]] || {
    echo 'Docker engine ID is empty.' >&2
    return 1
  }
  [[ -z "$expected_engine_id" || "$engine_id" == "$expected_engine_id" ]] || {
    echo 'Docker engine identity changed while the PostgreSQL transition controller was active.' >&2
    return 1
  }
  lock_key=$(printf '%s\0%s' "$engine_id" noosphere_postgres_data | sha256sum | awk '{print $1}')
  lock_path="$lock_root/noosphere-pgvector-switch-$lock_key.lock"
  exec 8>"$lock_path"
  flock -w 5 8 || {
    echo 'Another installer or PostgreSQL image switch is active for noosphere_postgres_data.' >&2
    return 1
  }
  export NOOSPHERE_A2B_LOCK_FD=8
  export NOOSPHERE_A2B_LOCK_PATH="$lock_path"
}

reacquire_postgres_operation_lock_from_manifest() {
  local expected_docker_host expected_engine_id expected_lock_root
  assert_installer_owned_regular_file "$POSTGRES_CONTROLLER_MANIFEST" || return 1
  expected_docker_host=$(jq -er '.dockerEndpoint | select(type == "string" and length > 0)' \
    "$POSTGRES_CONTROLLER_MANIFEST") || return 1
  expected_engine_id=$(jq -er '.engineId | select(type == "string" and length > 0)' \
    "$POSTGRES_CONTROLLER_MANIFEST") || return 1
  expected_lock_root=$(jq -er '.lockRoot | select(type == "string" and startswith("/"))' \
    "$POSTGRES_CONTROLLER_MANIFEST") || return 1
  acquire_postgres_operation_lock "$expected_docker_host" "$expected_engine_id" "$expected_lock_root"
}

extract_bootstrap_json() {
  local file="$1"
  BOOTSTRAP_JSON_FILE="$file" node -e '
    const fs = require("fs");
    const path = process.env.BOOTSTRAP_JSON_FILE;
    const lines = fs.readFileSync(path, "utf8").split(/\r?\n/);
    for (let i = lines.length - 1; i >= 0; i -= 1) {
      const line = lines[i].trim();
      if (!line || line.startsWith("[bootstrap]")) continue;
      try {
        JSON.parse(line);
        process.stdout.write(line);
        process.exit(0);
      } catch {
        // Keep walking upward; Docker/Prisma may emit status lines after JSON.
      }
    }
    process.exit(1);
  '
}

has_controlling_tty() {
  { : < /dev/tty; } 2>/dev/null
}

can_prompt() {
  [ -t 0 ] || has_controlling_tty
}

read_prompt() {
  local prompt="$1"
  local var_name="$2"

  if [ -t 0 ]; then
    read -r -p "$prompt" "$var_name"
  elif has_controlling_tty; then
    read -r -p "$prompt" "$var_name" < /dev/tty
  else
    return 1
  fi
}

# Validate an IPv4 address with proper octet range checking (0-255)
is_valid_ipv4() {
  local ip="$1"
  local IFS='.'
  local -a octets
  read -ra octets <<< "$ip"
  [[ ${#octets[@]} -eq 4 ]] || return 1
  for octet in "${octets[@]}"; do
    [[ "$octet" =~ ^[0-9]+$ ]] && (( 10#$octet >= 0 && 10#$octet <= 255 )) || return 1
  done
}

# Detect available IP addresses for the user to choose from
detect_ips() {
  local ips=()

  # Always include localhost
  ips+=("127.0.0.1")

  # Tailscale IP if available
  local tailscale_ip
  tailscale_ip="$(ip addr show tailscale0 2>/dev/null | awk '/inet / {print $2}' | cut -d/ -f1 | head -1 || true)"
  if [ -n "$tailscale_ip" ]; then
    ips+=("$tailscale_ip")
  fi

  # Other local network IPs (exclude loopback and docker)
  local network_ips
  network_ips="$(ip -4 addr show 2>/dev/null | awk '/inet / && !/127\.0\.0\.1/ && !/docker/ && !/br-/ {print $2}' | cut -d/ -f1 | sort -u || true)"
  if [ -n "$network_ips" ]; then
    while IFS= read -r ip; do
      [ -n "$ip" ] && ips+=("$ip")
    done <<< "$network_ips"
  fi

  # Deduplicate while preserving order
  local uniq_ips=()
  local seen=""
  for ip in "${ips[@]}"; do
    if [[ "$seen" != *"|$ip|"* ]]; then
      uniq_ips+=("$ip")
      seen="${seen}|${ip}|"
    fi
  done

  printf '%s\n' "${uniq_ips[@]}"
}

# Prompt user to select an IP address
prompt_ip_selection() {
  local ips
  ips="$(detect_ips)"
  local ip_array=()
  local idx=1

  echo ""
  echo "==================================="
  echo "  Noosphere Network Configuration"
  echo "==================================="
  echo ""
  echo "Available network interfaces:"
  echo ""

  while IFS= read -r ip; do
    [ -z "$ip" ] && continue
    ip_array+=("$ip")
    echo "  [$idx] $ip"
    ((idx++))
  done <<< "$ips"

  echo "  [0] 0.0.0.0 (all interfaces)"
  echo "  [C] Custom IP address"
  echo ""

  local selection
  local selected_ip=""
  local bind_addr=""
  local explicit_choice=false

  while true; do
    read_prompt "Select an IP address for Noosphere [1]: " selection
    selection="${selection:-1}"

    if [[ "$selection" =~ ^[Cc]$ ]]; then
      read_prompt "Enter custom IP address: " selected_ip
      if [ -z "$selected_ip" ]; then
        echo "IP address cannot be empty."
        continue
      fi
      # Normalize localhost to 127.0.0.1 for reliable Docker binding
      if [ "$selected_ip" = "localhost" ]; then
        selected_ip="127.0.0.1"
      fi
      # Basic IPv4 validation (reject obvious garbage before Docker does)
      if ! is_valid_ipv4 "$selected_ip"; then
        echo "Invalid IP address format. Please enter a valid IPv4 address."
        continue
      fi
      bind_addr="$selected_ip"
      explicit_choice=true
      break
    elif [[ "$selection" == "0" ]]; then
      bind_addr="0.0.0.0"
      explicit_choice=true
      break
    elif [[ "$selection" =~ ^[0-9]+$ ]] && [ "$selection" -ge 1 ] && [ "$selection" -le "${#ip_array[@]}" ]; then
      selected_ip="${ip_array[$((selection - 1))]}"
      bind_addr="$selected_ip"
      if [ "$selection" != "1" ]; then
        explicit_choice=true
      fi
      break
    else
      echo "Invalid selection. Please try again."
    fi
  done

  # When binding to all interfaces, APP_URL needs a concrete reachable address
  if [ "$bind_addr" = "0.0.0.0" ]; then
    if [ "${#ip_array[@]}" -ge 2 ]; then
      # Use first non-localhost IP from the list
      selected_ip="${ip_array[1]}"
    elif [ "${#ip_array[@]}" -ge 1 ]; then
      selected_ip="${ip_array[0]}"
    else
      selected_ip="127.0.0.1"
    fi
  fi

  # Format APP_URL: IPv6 addresses need brackets
  if [[ "$selected_ip" == *":"* ]]; then
    APP_URL="http://[${selected_ip}]:${NOOSPHERE_PORT}"
  else
    APP_URL="http://${selected_ip}:${NOOSPHERE_PORT}"
  fi
  # Only override BIND_ADDRESS if not already set by user
  if [ -z "${BIND_ADDRESS}" ]; then
    BIND_ADDRESS="$bind_addr"
  fi

  echo ""
  echo "Noosphere will be accessible at: ${APP_URL}"
  if [ "$bind_addr" = "0.0.0.0" ]; then
    echo "WARNING: Binding to all interfaces (0.0.0.0) exposes Noosphere on all network interfaces."
  elif [ "$selected_ip" != "127.0.0.1" ]; then
    echo "Note: Binding to ${bind_addr} - ensure your firewall allows access to port ${NOOSPHERE_PORT}."
  fi
  echo ""

  if [ "$explicit_choice" = true ]; then
    local continue_ack=""
    read_prompt "Press Enter to continue or Ctrl+C to abort..." continue_ack
    echo ""
  fi
}

wait_for_container_healthy() {
  local name="$1"
  local attempts="${2:-60}"
  for _ in $(seq 1 "$attempts"); do
    local status
    status="$(docker inspect --format='{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' "$name" 2>/dev/null || true)"
    if [ "$status" = "healthy" ] || [ "$status" = "running" ]; then
      return 0
    fi
    sleep 2
  done
  echo "Container did not become healthy/running: $name" >&2
  docker logs "$name" --tail 80 >&2 || true
  exit 1
}

wait_for_http_health() {
  local url="$1"
  local attempts="${2:-60}"
  for _ in $(seq 1 "$attempts"); do
    if local_no_proxy_curl -fsS "$url/api/health" >/dev/null 2>&1; then
      return 0
    fi
    sleep 2
  done
  echo "Noosphere health check failed: $url/api/health" >&2
  docker logs noosphere-openclaw-app --tail 120 >&2 || true
  exit 1
}

capture_article_verification_floor() {
  local db_container=$1 fresh_install=$2 count=''
  if [[ "$fresh_install" == true ]]; then
    printf '0\n'
    return 0
  fi
  count="$(
    docker exec "$db_container" psql -XAtq -v ON_ERROR_STOP=1 \
      -U noosphere -d noosphere \
      -c 'SELECT count(*) FROM "Article" WHERE "deletedAt" IS NULL;'
  )" || {
    echo 'Failed to capture the pre-install article-count preservation floor.' >&2
    return 1
  }
  [[ "$count" =~ ^[0-9]+$ ]] || {
    echo 'Pre-install article count is not a non-negative integer.' >&2
    return 1
  }
  printf '%s\n' "$count"
}

main() {
case "$NOOSPHERE_INSTALL_OPENCLAW" in
  true|false) ;;
  *) echo 'NOOSPHERE_INSTALL_OPENCLAW must be exactly true or false.' >&2; exit 1 ;;
esac
case "$NOOSPHERE_SHOW_CREDENTIALS" in
  true|false) ;;
  *) echo 'NOOSPHERE_SHOW_CREDENTIALS must be exactly true or false.' >&2; exit 1 ;;
esac
need docker
need node
need curl
if [[ "$NOOSPHERE_INSTALL_OPENCLAW" == true ]]; then
  need openclaw
fi
need jq
need sha256sum
need flock
need realpath

if ! docker compose version >/dev/null 2>&1; then
  echo "Docker Compose v2 is required: docker compose" >&2
  exit 1
fi

mkdir -p "$NOOSPHERE_HOME"
if [[ "$NOOSPHERE_INSTALL_OPENCLAW" == true ]]; then
  mkdir -p "$SECRETS_DIR"
  chmod 700 "$SECRETS_DIR" || true
fi
POSTGRES_BACKUP_DIR="$NOOSPHERE_HOME/backups/postgres-pgvector"
controller_transition_completed=false
acquire_postgres_operation_lock
resolve_runtime_config
prepare_postgres_controller_runtime

# Resume or reconcile controller-owned state before prompts or runtime-config
# writes can change bound inputs.
reconcile_postgres_controller_before_configuration

# Detect whether prompts can be shown. In `curl | bash`, stdin is the
# installer pipe, so use /dev/tty when a controlling terminal is available.
IS_INTERACTIVE=false
if can_prompt; then
  IS_INTERACTIVE=true
fi

# Auto-detect the best IP for non-interactive mode
auto_detect_ip() {
  local ts_ip
  ts_ip="$(ip addr show tailscale0 2>/dev/null | awk '/inet / {print $2}' | cut -d/ -f1 | head -1 || true)"
  if [ -n "$ts_ip" ]; then
    APP_URL="http://${ts_ip}:${NOOSPHERE_PORT}"
    if [ -z "${BIND_ADDRESS}" ]; then
      BIND_ADDRESS="$ts_ip"
    fi
  else
    APP_URL="http://127.0.0.1:${NOOSPHERE_PORT}"
    if [ -z "${BIND_ADDRESS}" ]; then
      BIND_ADDRESS="127.0.0.1"
    fi
  fi
}

# IP selection happens BEFORE any container operations
if [ -z "${APP_URL:-}" ]; then
  if [ "$IS_INTERACTIVE" = true ]; then
    prompt_ip_selection
  else
    auto_detect_ip
    echo "No interactive terminal detected. Auto-selected: ${APP_URL}"
  fi
else
  # APP_URL was provided via environment variable
  if [ -z "${BIND_ADDRESS}" ]; then
    BIND_ADDRESS="127.0.0.1"
    # Extract host from APP_URL for binding using bash parameter expansion
    url_host="${APP_URL#*://}"
    url_host="${url_host%%:*}"
    url_host="${url_host%%/*}"
    # Only use the extracted host for binding if it's a valid IP literal.
    # Docker port bindings require an IP, not a hostname.
    if [ -n "$url_host" ] && is_valid_ipv4 "$url_host"; then
      BIND_ADDRESS="$url_host"
    fi
  fi
fi

POSTGRES_PASSWORD="$EXPLICIT_POSTGRES_PASSWORD"
POSTGRES_MIGRATION_PASSWORD="$EXPLICIT_POSTGRES_MIGRATION_PASSWORD"
POSTGRES_APP_PASSWORD="$EXPLICIT_POSTGRES_APP_PASSWORD"
POSTGRES_HYBRID_ADMIN_PASSWORD="$EXPLICIT_POSTGRES_HYBRID_ADMIN_PASSWORD"
POSTGRES_HYBRID_WORKER_PASSWORD="$EXPLICIT_POSTGRES_HYBRID_WORKER_PASSWORD"
NEXTAUTH_SECRET="$EXPLICIT_NEXTAUTH_SECRET"
ADMIN_PASSWORD="$EXPLICIT_ADMIN_PASSWORD"
API_KEY="$EXPLICIT_API_KEY"

# The installer-managed runtime file is the persistent source of truth. A
# non-empty process value wins for this run; otherwise prefer .env before the
# derived OpenClaw secret file so a deliberate .env edit is never shadowed by a
# stale credential copy.
POSTGRES_PASSWORD="${POSTGRES_PASSWORD:-$(env_get_secret "$NOOSPHERE_HOME/.env" POSTGRES_PASSWORD)}"
POSTGRES_MIGRATION_PASSWORD="${POSTGRES_MIGRATION_PASSWORD:-$(env_get_secret "$NOOSPHERE_HOME/.env" POSTGRES_MIGRATION_PASSWORD)}"
POSTGRES_APP_PASSWORD="${POSTGRES_APP_PASSWORD:-$(env_get_secret "$NOOSPHERE_HOME/.env" POSTGRES_APP_PASSWORD)}"
POSTGRES_HYBRID_ADMIN_PASSWORD="${POSTGRES_HYBRID_ADMIN_PASSWORD:-$(env_get_secret "$NOOSPHERE_HOME/.env" POSTGRES_HYBRID_ADMIN_PASSWORD)}"
POSTGRES_HYBRID_WORKER_PASSWORD="${POSTGRES_HYBRID_WORKER_PASSWORD:-$(env_get_secret "$NOOSPHERE_HOME/.env" POSTGRES_HYBRID_WORKER_PASSWORD)}"
NEXTAUTH_SECRET="${NEXTAUTH_SECRET:-$(env_get_secret "$NOOSPHERE_HOME/.env" NEXTAUTH_SECRET)}"
ADMIN_PASSWORD="${ADMIN_PASSWORD:-$(env_get_secret "$NOOSPHERE_HOME/.env" NOOSPHERE_ADMIN_PASSWORD)}"
API_KEY="${API_KEY:-$(env_get_secret "$NOOSPHERE_HOME/.env" NOOSPHERE_BOOTSTRAP_API_KEY)}"
EXISTING_INTEGRATION_API_KEY="$(json_get "$NOOSPHERE_CREDENTIALS_FILE" apiKey)"
INTEGRATION_API_KEY=""
NOOSPHERE_BOOTSTRAP_SECRETS_FILE="${NOOSPHERE_BOOTSTRAP_SECRETS_FILE:-$(env_get_secret "$NOOSPHERE_HOME/.env" NOOSPHERE_BOOTSTRAP_SECRETS_FILE)}"

POSTGRES_PASSWORD="${POSTGRES_PASSWORD:-$(json_get "$SECRETS_FILE" postgresPassword)}"
POSTGRES_MIGRATION_PASSWORD="${POSTGRES_MIGRATION_PASSWORD:-$(json_get "$SECRETS_FILE" postgresMigrationPassword)}"
POSTGRES_APP_PASSWORD="${POSTGRES_APP_PASSWORD:-$(json_get "$SECRETS_FILE" postgresAppPassword)}"
POSTGRES_HYBRID_ADMIN_PASSWORD="${POSTGRES_HYBRID_ADMIN_PASSWORD:-$(json_get "$SECRETS_FILE" postgresHybridAdminPassword)}"
POSTGRES_HYBRID_WORKER_PASSWORD="${POSTGRES_HYBRID_WORKER_PASSWORD:-$(json_get "$SECRETS_FILE" postgresHybridWorkerPassword)}"
NEXTAUTH_SECRET="${NEXTAUTH_SECRET:-$(json_get "$SECRETS_FILE" nextAuthSecret)}"
ADMIN_PASSWORD="${ADMIN_PASSWORD:-$(json_get "$SECRETS_FILE" adminPassword)}"
API_KEY="${API_KEY:-$(json_get "$SECRETS_FILE" apiKey)}"

POSTGRES_PASSWORD="${POSTGRES_PASSWORD:-$(random_secret 32)}"
POSTGRES_MIGRATION_PASSWORD="${POSTGRES_MIGRATION_PASSWORD:-$(random_secret 32)}"
POSTGRES_APP_PASSWORD="${POSTGRES_APP_PASSWORD:-$(random_secret 32)}"
POSTGRES_HYBRID_ADMIN_PASSWORD="${POSTGRES_HYBRID_ADMIN_PASSWORD:-$(random_secret 32)}"
POSTGRES_HYBRID_WORKER_PASSWORD="${POSTGRES_HYBRID_WORKER_PASSWORD:-$(random_secret 32)}"
NEXTAUTH_SECRET="${NEXTAUTH_SECRET:-$(random_secret 32)}"
ADMIN_PASSWORD="${ADMIN_PASSWORD:-$(random_secret 24)}"
API_KEY="${API_KEY:-noo_$(random_secret 32)}"
NOOSPHERE_ADMIN_PASSWORD_RESET="${NOOSPHERE_ADMIN_PASSWORD_RESET:-false}"
NOOSPHERE_FORCE_ADMIN="${NOOSPHERE_FORCE_ADMIN:-false}"
NOOSPHERE_BOOTSTRAP_SECRETS_FILE="${NOOSPHERE_BOOTSTRAP_SECRETS_FILE:-/tmp/noosphere-bootstrap-secrets/secrets.json}"
normalize_hybrid_provider_config
if [[ "$NOOSPHERE_HYBRID_RETRIEVAL_ENABLED_WAS_SET" == 0 ]]; then
  if env_has_key "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_RETRIEVAL_ENABLED; then
    NOOSPHERE_HYBRID_RETRIEVAL_ENABLED="$(
      env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_RETRIEVAL_ENABLED
    )"
  else
    NOOSPHERE_HYBRID_RETRIEVAL_ENABLED=false
  fi
fi
NOOSPHERE_HYBRID_QUERY_PROFILE_ID="${NOOSPHERE_HYBRID_QUERY_PROFILE_ID:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_QUERY_PROFILE_ID)}"
NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION="${NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION)}"
normalize_hybrid_retrieval_config
NOOSPHERE_HYBRID_WORKER_CONCURRENCY="${NOOSPHERE_HYBRID_WORKER_CONCURRENCY:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_WORKER_CONCURRENCY)}"
NOOSPHERE_HYBRID_WORKER_CONCURRENCY="${NOOSPHERE_HYBRID_WORKER_CONCURRENCY:-4}"
NOOSPHERE_HYBRID_LEASE_SECONDS="${NOOSPHERE_HYBRID_LEASE_SECONDS:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_LEASE_SECONDS)}"
NOOSPHERE_HYBRID_LEASE_SECONDS="${NOOSPHERE_HYBRID_LEASE_SECONDS:-120}"
NOOSPHERE_HYBRID_MAX_ATTEMPTS="${NOOSPHERE_HYBRID_MAX_ATTEMPTS:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_MAX_ATTEMPTS)}"
NOOSPHERE_HYBRID_MAX_ATTEMPTS="${NOOSPHERE_HYBRID_MAX_ATTEMPTS:-8}"
NOOSPHERE_HYBRID_WORKER_POLL_MS="${NOOSPHERE_HYBRID_WORKER_POLL_MS:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_WORKER_POLL_MS)}"
NOOSPHERE_HYBRID_WORKER_POLL_MS="${NOOSPHERE_HYBRID_WORKER_POLL_MS:-1000}"
NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS="${NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS)}"
NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS="${NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS:-30000}"
NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES="${NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES)}"
NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES="${NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES:-4194304}"
NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH="${NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH)}"
NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH="${NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH:-1000}"
NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH="${NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH)}"
NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH="${NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH:-10000}"
NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS="${NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS)}"
NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS="${NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS:-300}"
NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS="${NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS:-$(env_get "$NOOSPHERE_HOME/.env" NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS)}"
NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS="${NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS:-1800}"

reject_multiline_env_value NOOSPHERE_VERSION "$NOOSPHERE_VERSION"
reject_multiline_env_value NOOSPHERE_IMAGE "$NOOSPHERE_IMAGE"
reject_multiline_env_value NOOSPHERE_PORT "$NOOSPHERE_PORT"
reject_multiline_env_value APP_URL "$APP_URL"
reject_multiline_env_value BIND_ADDRESS "$BIND_ADDRESS"
reject_multiline_env_value POSTGRES_PASSWORD "$POSTGRES_PASSWORD"
reject_multiline_env_value POSTGRES_MIGRATION_PASSWORD "$POSTGRES_MIGRATION_PASSWORD"
reject_multiline_env_value POSTGRES_APP_PASSWORD "$POSTGRES_APP_PASSWORD"
reject_multiline_env_value POSTGRES_HYBRID_ADMIN_PASSWORD "$POSTGRES_HYBRID_ADMIN_PASSWORD"
reject_multiline_env_value POSTGRES_HYBRID_WORKER_PASSWORD "$POSTGRES_HYBRID_WORKER_PASSWORD"
reject_multiline_env_value NEXTAUTH_SECRET "$NEXTAUTH_SECRET"
reject_multiline_env_value NOOSPHERE_ADMIN_PASSWORD "$ADMIN_PASSWORD"
reject_multiline_env_value NOOSPHERE_ADMIN_PASSWORD_RESET "$NOOSPHERE_ADMIN_PASSWORD_RESET"
reject_multiline_env_value NOOSPHERE_FORCE_ADMIN "$NOOSPHERE_FORCE_ADMIN"
reject_multiline_env_value NOOSPHERE_BOOTSTRAP_API_KEY "$API_KEY"
reject_multiline_env_value NOOSPHERE_BOOTSTRAP_SECRETS_FILE "$NOOSPHERE_BOOTSTRAP_SECRETS_FILE"
reject_multiline_env_value REDIS_URL "$REDIS_URL"
reject_multiline_env_value PG_POOL_MAX "$PG_POOL_MAX"
reject_multiline_env_value PG_IDLE_TIMEOUT_MS "$PG_IDLE_TIMEOUT_MS"
reject_multiline_env_value PG_CONN_TIMEOUT_MS "$PG_CONN_TIMEOUT_MS"
reject_multiline_env_value NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE "$NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE"
reject_multiline_env_value NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64 "$NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64"
reject_multiline_env_value NOOSPHERE_HYBRID_RETRIEVAL_ENABLED "$NOOSPHERE_HYBRID_RETRIEVAL_ENABLED"
reject_multiline_env_value NOOSPHERE_HYBRID_QUERY_PROFILE_ID "$NOOSPHERE_HYBRID_QUERY_PROFILE_ID"
reject_multiline_env_value NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION "$NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION"
reject_multiline_env_value NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64 "$NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64"
reject_multiline_env_value NOOSPHERE_HYBRID_WORKER_CONCURRENCY "$NOOSPHERE_HYBRID_WORKER_CONCURRENCY"
reject_multiline_env_value NOOSPHERE_HYBRID_LEASE_SECONDS "$NOOSPHERE_HYBRID_LEASE_SECONDS"
reject_multiline_env_value NOOSPHERE_HYBRID_MAX_ATTEMPTS "$NOOSPHERE_HYBRID_MAX_ATTEMPTS"
reject_multiline_env_value NOOSPHERE_HYBRID_WORKER_POLL_MS "$NOOSPHERE_HYBRID_WORKER_POLL_MS"
reject_multiline_env_value NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS "$NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS"
reject_multiline_env_value NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES "$NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES"
reject_multiline_env_value NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH "$NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH"
reject_multiline_env_value NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH "$NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH"
reject_multiline_env_value NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS "$NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS"
reject_multiline_env_value NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS "$NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS"

# Export Compose variables. Bootstrap credentials are exported too because
# docker compose up may run the init service again through app.depends_on; the
# second run must see the same admin/API credentials as the explicit bootstrap
# run below.
[[ "$POSTGRES_PASSWORD" != "$POSTGRES_MIGRATION_PASSWORD" &&
   "$POSTGRES_PASSWORD" != "$POSTGRES_APP_PASSWORD" &&
   "$POSTGRES_PASSWORD" != "$POSTGRES_HYBRID_ADMIN_PASSWORD" &&
   "$POSTGRES_PASSWORD" != "$POSTGRES_HYBRID_WORKER_PASSWORD" &&
   "$POSTGRES_MIGRATION_PASSWORD" != "$POSTGRES_APP_PASSWORD" &&
   "$POSTGRES_MIGRATION_PASSWORD" != "$POSTGRES_HYBRID_ADMIN_PASSWORD" &&
   "$POSTGRES_MIGRATION_PASSWORD" != "$POSTGRES_HYBRID_WORKER_PASSWORD" &&
   "$POSTGRES_APP_PASSWORD" != "$POSTGRES_HYBRID_ADMIN_PASSWORD" &&
   "$POSTGRES_APP_PASSWORD" != "$POSTGRES_HYBRID_WORKER_PASSWORD" &&
   "$POSTGRES_HYBRID_ADMIN_PASSWORD" != "$POSTGRES_HYBRID_WORKER_PASSWORD" ]] || {
  echo 'PostgreSQL bootstrap, migration, application, hybrid-admin, and hybrid-worker passwords must be distinct.' >&2
  exit 1
}

export NOOSPHERE_VERSION NOOSPHERE_PORT NOOSPHERE_IMAGE APP_URL BIND_ADDRESS POSTGRES_PASSWORD POSTGRES_MIGRATION_PASSWORD POSTGRES_APP_PASSWORD POSTGRES_HYBRID_ADMIN_PASSWORD POSTGRES_HYBRID_WORKER_PASSWORD NEXTAUTH_SECRET REDIS_URL NOOSPHERE_BOOTSTRAP_SECRETS_FILE NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE
export NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64 NOOSPHERE_HYBRID_WORKER_CONCURRENCY NOOSPHERE_HYBRID_LEASE_SECONDS NOOSPHERE_HYBRID_MAX_ATTEMPTS NOOSPHERE_HYBRID_WORKER_POLL_MS NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS
export NOOSPHERE_HYBRID_RETRIEVAL_ENABLED NOOSPHERE_HYBRID_QUERY_PROFILE_ID NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64
export NOOSPHERE_ADMIN_PASSWORD="$ADMIN_PASSWORD"
export NOOSPHERE_BOOTSTRAP_API_KEY="$API_KEY"

# Persist the effective role credentials atomically. This is append-only for
# an older file without the A3 keys, while an explicit password rotation must
# replace the corresponding assignment so the next restart cannot fall back
# to a stale credential.
if [[ ! -f "$NOOSPHERE_HOME/.env" ]]; then
  write_runtime_env
else
  chmod 600 "$NOOSPHERE_HOME/.env"
  ensure_runtime_env_secret POSTGRES_MIGRATION_PASSWORD "$POSTGRES_MIGRATION_PASSWORD"
  ensure_runtime_env_secret POSTGRES_APP_PASSWORD "$POSTGRES_APP_PASSWORD"
  ensure_runtime_env_secret POSTGRES_HYBRID_ADMIN_PASSWORD "$POSTGRES_HYBRID_ADMIN_PASSWORD"
  ensure_runtime_env_secret POSTGRES_HYBRID_WORKER_PASSWORD "$POSTGRES_HYBRID_WORKER_PASSWORD"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64 "$NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_RETRIEVAL_ENABLED "$NOOSPHERE_HYBRID_RETRIEVAL_ENABLED"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_QUERY_PROFILE_ID "$NOOSPHERE_HYBRID_QUERY_PROFILE_ID"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION "$NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64 "$NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_WORKER_CONCURRENCY "$NOOSPHERE_HYBRID_WORKER_CONCURRENCY"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_LEASE_SECONDS "$NOOSPHERE_HYBRID_LEASE_SECONDS"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_MAX_ATTEMPTS "$NOOSPHERE_HYBRID_MAX_ATTEMPTS"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_WORKER_POLL_MS "$NOOSPHERE_HYBRID_WORKER_POLL_MS"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS "$NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES "$NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH "$NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH "$NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS "$NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS"
  ensure_runtime_env_secret NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS "$NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS"
fi

new_install_required=false
existing_switch_required=false
postgres_evidence="$POSTGRES_BACKUP_DIR/noosphere_postgres_data.phase-a2b.json"
incomplete_new_install=false
incomplete_switch=false
resume_recovered_switch=false
postgres_transition_complete=false
if [[ -f "$postgres_evidence" ]] &&
   jq -e '.mode == "new-install" and (.phase == "claim-created" or .phase == "provisioning")' \
     "$postgres_evidence" >/dev/null 2>&1; then
  incomplete_new_install=true
fi
if [[ -f "$postgres_evidence" ]] &&
   jq -e '.mode == "switch" and .phase != "complete"' "$postgres_evidence" >/dev/null 2>&1; then
  incomplete_switch=true
fi
if [[ -f "$postgres_evidence" ]] &&
   jq -e '.mode == "switch" and .phase == "recovered"' "$postgres_evidence" >/dev/null 2>&1; then
  resume_recovered_switch=true
fi
if [[ -f "$postgres_evidence" ]] &&
   jq -e '(.mode == "switch" or .mode == "new-install") and .phase == "complete"' \
     "$postgres_evidence" >/dev/null 2>&1; then
  postgres_transition_complete=true
fi
if [[ -e "$POSTGRES_CONTROLLER_STATE" ]] &&
   jq -e '.phase == "complete"' "$POSTGRES_CONTROLLER_STATE" >/dev/null 2>&1 &&
   [[ "$postgres_transition_complete" != true ]]; then
  echo 'Controller state is complete but the bound PostgreSQL guard journal is not; refusing to continue.' >&2
  exit 1
fi

if docker inspect noosphere-openclaw-db >/dev/null 2>&1; then
  if [[ "$incomplete_new_install" == true ]]; then
    new_install_required=true
    docker stop --time 60 noosphere-openclaw-app >/dev/null 2>&1 || true
  elif [[ "$postgres_transition_complete" == true ]]; then
    existing_switch_required=false
  else
    [[ -f "$NOOSPHERE_HOME/docker-compose.yml" ]] || {
      echo 'Existing database container has no installer-managed Compose file; refusing an unguarded upgrade.' >&2
      exit 1
    }
    existing_switch_required=true
  fi
elif docker volume inspect noosphere_postgres_data >/dev/null 2>&1; then
  if [[ "$incomplete_new_install" == true ]]; then
    new_install_required=true
    docker stop --time 60 noosphere-openclaw-app >/dev/null 2>&1 || true
  elif [[ "$incomplete_switch" == true ]]; then
    existing_switch_required=true
    docker stop --time 60 noosphere-openclaw-app >/dev/null 2>&1 || true
  else
    echo 'Existing PostgreSQL volume has no managed database container or durable new-install claim.' >&2
    exit 1
  fi
else
  if [[ -f "$postgres_evidence" && "$incomplete_new_install" != true ]]; then
    echo 'PostgreSQL transition evidence exists but its named volume is missing; refusing a new install.' >&2
    exit 1
  fi
  new_install_required=true
fi

# A durable recovered journal means the exact-source database, authorization
# marker, and source-gated Compose file have already crossed the rollback
# commit boundary. Let the guard verify and archive that state before this
# installer publishes any candidate desired state. The guard deliberately
# returns non-zero after recovery, so the operator must rerun from a fresh
# transaction rather than continuing in the same invocation.
if [[ "$resume_recovered_switch" == true ]]; then
  echo 'Finalizing the verified PostgreSQL source recovery before publishing the candidate template...'
  recovered_exit=0
  "$POSTGRES_SWITCH_SCRIPT" \
    --compose-file "$NOOSPHERE_HOME/docker-compose.yml" \
    --env-file "$NOOSPHERE_HOME/.env" \
    --db-container noosphere-openclaw-db \
    --app-container noosphere-openclaw-app \
    --backup-dir "$POSTGRES_BACKUP_DIR" \
    --defer-app-restart || recovered_exit=$?
  if (( recovered_exit == 0 )); then
    echo 'Recovered PostgreSQL evidence unexpectedly returned success; refusing to continue in the same installer run.' >&2
    exit 1
  fi
  exit "$recovered_exit"
fi

compose_target="$NOOSPHERE_HOME/docker-compose.yml"
if [[ "$existing_switch_required" == true ]]; then
  install -m 600 "$NOOSPHERE_HOME/docker-compose.yml" "$POSTGRES_CONTROLLER_SOURCE"
  fsync_installer_path "$POSTGRES_CONTROLLER_SOURCE"
  fsync_installer_path "$POSTGRES_CONTROLLER_ROOT"
  compose_target="$POSTGRES_CONTROLLER_CANDIDATE"
fi

cat > "$compose_target" <<YAML
name: noosphere

services:
  init:
    image: ${NOOSPHERE_IMAGE}
    container_name: noosphere-openclaw-init
    restart: "no"
    environment:
      NOOSPHERE_BOOTSTRAP_DATABASE_URL: postgresql://noosphere:\${POSTGRES_PASSWORD}@db:5432/noosphere
      DATABASE_URL: postgresql://noosphere_migrator:\${POSTGRES_MIGRATION_PASSWORD}@db:5432/noosphere
      NOOSPHERE_APP_DATABASE_URL: postgresql://noosphere_app:\${POSTGRES_APP_PASSWORD}@db:5432/noosphere
      POSTGRES_HYBRID_ADMIN_PASSWORD: \${POSTGRES_HYBRID_ADMIN_PASSWORD:-}
      POSTGRES_HYBRID_WORKER_PASSWORD: \${POSTGRES_HYBRID_WORKER_PASSWORD:-}
      NOOSPHERE_ADMIN_PASSWORD: \${NOOSPHERE_ADMIN_PASSWORD}
      NOOSPHERE_ADMIN_PASSWORD_RESET: \${NOOSPHERE_ADMIN_PASSWORD_RESET:-false}
      NOOSPHERE_FORCE_ADMIN: \${NOOSPHERE_FORCE_ADMIN:-false}
      NOOSPHERE_BOOTSTRAP_API_KEY: \${NOOSPHERE_BOOTSTRAP_API_KEY}
      # Keep the default in a dedicated directory because bootstrap tightens the
      # parent directory to 0700 before writing the 0600 credentials file.
      NOOSPHERE_BOOTSTRAP_SECRETS_FILE: \${NOOSPHERE_BOOTSTRAP_SECRETS_FILE:-/tmp/noosphere-bootstrap-secrets/secrets.json}
      NEXTAUTH_SECRET: \${NEXTAUTH_SECRET}
      NEXTAUTH_URL: \${APP_URL:-http://127.0.0.1:6578}
      APP_URL: \${APP_URL:-http://127.0.0.1:6578}
      UPLOAD_DIR: /app/uploads
      PG_POOL_MAX: \${PG_POOL_MAX:-20}
      PG_IDLE_TIMEOUT_MS: \${PG_IDLE_TIMEOUT_MS:-30000}
      PG_CONN_TIMEOUT_MS: \${PG_CONN_TIMEOUT_MS:-5000}
      REDIS_URL: \${REDIS_URL:-redis://redis:6379}
      NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE: \${NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE:-120}
    entrypoint: ["/bin/sh", "-ceu", "--"]
    command:
      - |
          if [ -n "\$\$POSTGRES_HYBRID_ADMIN_PASSWORD" ] || [ -n "\$\$POSTGRES_HYBRID_WORKER_PASSWORD" ]; then
            if [ -z "\$\$POSTGRES_HYBRID_ADMIN_PASSWORD" ] || [ -z "\$\$POSTGRES_HYBRID_WORKER_PASSWORD" ]; then
              echo 'Both Phase B database passwords must be configured together.' >&2
              exit 78
            fi
            export NOOSPHERE_HYBRID_ADMIN_DATABASE_URL="postgresql://noosphere_hybrid_admin_login:\$\$POSTGRES_HYBRID_ADMIN_PASSWORD@db:5432/noosphere"
            export NOOSPHERE_HYBRID_WORKER_DATABASE_URL="postgresql://noosphere_hybrid_worker_login:\$\$POSTGRES_HYBRID_WORKER_PASSWORD@db:5432/noosphere"
          fi
          node docker/provision-database-roles.mjs
          node docker/migrate-or-baseline.mjs
          # Migrations may create tables or routines. Re-provision so the
          # limited app role receives only the current exact runtime grants.
          node docker/provision-database-roles.mjs
          node docker/bootstrap.mjs
    volumes:
      - noosphere_uploads:/app/uploads:rw
    depends_on:
      db:
        condition: service_healthy

  app:
    image: ${NOOSPHERE_IMAGE}
    entrypoint:
      - /bin/sh
      - -ceu
      - |
          marker=/run/noosphere-pgvector/writer-authorized
          actual="\$\$(cat "\$\$marker" 2>/dev/null || true)"
          if [ "\$\$actual" != 'ghcr.io/sweetsophia/noosphere-postgres-pgvector@sha256:12bc9b34226803a04811a3ddd06feac14121c2c7ce369aaddbd778d242751292' ]; then
            echo 'Noosphere writer authorization is incomplete; finish the guarded transition.' >&2
            exit 78
          fi
          exec /app/docker/docker-entrypoint.sh "\$\$@"
      - --
    command: ["node", "server.js"]
    container_name: noosphere-openclaw-app
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - "\${BIND_ADDRESS:-127.0.0.1}:\${NOOSPHERE_PORT:-6578}:3000"
    environment:
      DATABASE_URL: postgresql://noosphere_app:\${POSTGRES_APP_PASSWORD}@db:5432/noosphere
      SKIP_MIGRATION: "1"
      NEXTAUTH_SECRET: \${NEXTAUTH_SECRET}
      NEXTAUTH_URL: \${APP_URL:-http://127.0.0.1:6578}
      APP_URL: \${APP_URL:-http://127.0.0.1:6578}
      UPLOAD_DIR: /app/uploads
      PG_POOL_MAX: \${PG_POOL_MAX:-20}
      PG_IDLE_TIMEOUT_MS: \${PG_IDLE_TIMEOUT_MS:-30000}
      PG_CONN_TIMEOUT_MS: \${PG_CONN_TIMEOUT_MS:-5000}
      REDIS_URL: \${REDIS_URL:-redis://redis:6379}
      NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE: \${NOOSPHERE_MEMORY_RECALL_RATE_LIMIT_PER_MINUTE:-120}
      NOOSPHERE_HYBRID_RETRIEVAL_ENABLED: \${NOOSPHERE_HYBRID_RETRIEVAL_ENABLED-false}
      NOOSPHERE_HYBRID_QUERY_PROFILE_ID: \${NOOSPHERE_HYBRID_QUERY_PROFILE_ID:-}
      NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION: \${NOOSPHERE_HYBRID_CACHE_HMAC_ACTIVE_VERSION:-}
      NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64: \${NOOSPHERE_HYBRID_CACHE_HMAC_KEYS_B64:-}
      NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64: \${NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64:-W10=}
      NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS: \${NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS:-30000}
      NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES: \${NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES:-4194304}
    volumes:
      - noosphere_uploads:/app/uploads:rw
      - noosphere_postgres_authorization:/run/noosphere-pgvector:ro
    depends_on:
      init:
        condition: service_completed_successfully
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 45s

  hybrid-worker:
    image: ${NOOSPHERE_IMAGE}
    profiles: ["hybrid"]
    entrypoint:
      - /bin/sh
      - -ceu
      - |
          marker=/run/noosphere-pgvector/writer-authorized
          actual="\$\$(cat "\$\$marker" 2>/dev/null || true)"
          if [ "\$\$actual" != 'ghcr.io/sweetsophia/noosphere-postgres-pgvector@sha256:12bc9b34226803a04811a3ddd06feac14121c2c7ce369aaddbd778d242751292' ]; then
            echo 'Noosphere writer authorization is incomplete; finish the guarded transition.' >&2
            exit 78
          fi
          exec /app/docker/docker-entrypoint.sh "\$\$@"
      - --
    command: ["node", "scripts/hybrid-worker.mjs"]
    container_name: noosphere-openclaw-hybrid-worker
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      SKIP_MIGRATION: "1"
      NOOSPHERE_HYBRID_WORKER_DATABASE_URL: postgresql://noosphere_hybrid_worker_login:\${POSTGRES_HYBRID_WORKER_PASSWORD:-HYBRID_WORKER_PASSWORD_NOT_CONFIGURED}@db:5432/noosphere
      NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64: \${NOOSPHERE_HYBRID_PROVIDER_CONFIG_B64:-W10=}
      NOOSPHERE_HYBRID_WORKER_CONCURRENCY: \${NOOSPHERE_HYBRID_WORKER_CONCURRENCY:-4}
      NOOSPHERE_HYBRID_LEASE_SECONDS: \${NOOSPHERE_HYBRID_LEASE_SECONDS:-120}
      NOOSPHERE_HYBRID_MAX_ATTEMPTS: \${NOOSPHERE_HYBRID_MAX_ATTEMPTS:-8}
      NOOSPHERE_HYBRID_WORKER_POLL_MS: \${NOOSPHERE_HYBRID_WORKER_POLL_MS:-1000}
      NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS: \${NOOSPHERE_HYBRID_REQUEST_TIMEOUT_MS:-30000}
      NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES: \${NOOSPHERE_HYBRID_MAX_RESPONSE_BYTES:-4194304}
      NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH: \${NOOSPHERE_HYBRID_QUEUE_WARNING_DEPTH:-1000}
      NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH: \${NOOSPHERE_HYBRID_QUEUE_CRITICAL_DEPTH:-10000}
      NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS: \${NOOSPHERE_HYBRID_QUEUE_WARNING_AGE_SECONDS:-300}
      NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS: \${NOOSPHERE_HYBRID_QUEUE_CRITICAL_AGE_SECONDS:-1800}
      NOOSPHERE_HYBRID_WORKER_HEALTH_FILE: /tmp/noosphere-hybrid-worker/health.json
    volumes:
      - noosphere_postgres_authorization:/run/noosphere-pgvector:ro
    depends_on:
      init:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "node", "scripts/check-hybrid-worker-health.mjs"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

  db:
    image: ghcr.io/sweetsophia/noosphere-postgres-pgvector@sha256:12bc9b34226803a04811a3ddd06feac14121c2c7ce369aaddbd778d242751292
    entrypoint:
      - /bin/sh
      - -ceu
      - |
          marker=/run/noosphere-pgvector/candidate-authorized
          actual="\$\$(cat "\$\$marker" 2>/dev/null || true)"
          if [ "\$\$actual" != 'ghcr.io/sweetsophia/noosphere-postgres-pgvector@sha256:12bc9b34226803a04811a3ddd06feac14121c2c7ce369aaddbd778d242751292' ]; then
            echo 'PostgreSQL candidate authorization is missing; run the guarded installer or switch.' >&2
            exit 78
          fi
          exec /usr/local/bin/docker-entrypoint.sh "\$\$@"
      - --
    command: ["postgres"]
    container_name: noosphere-openclaw-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: noosphere
      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD}
      POSTGRES_DB: noosphere
    volumes:
      - noosphere_postgres_data:/var/lib/postgresql/data
      - noosphere_postgres_authorization:/run/noosphere-pgvector:ro
    healthcheck:
      test: ["CMD-SHELL", "[ \"\$\$(cat /proc/1/comm 2>/dev/null)\" = postgres ] && [ \"\$\$(psql -XAtq -v ON_ERROR_STOP=1 -U noosphere -d noosphere -c 'SELECT 1;' 2>/dev/null)\" = 1 ]"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

  redis:
    image: redis:7-alpine
    container_name: noosphere-openclaw-redis
    restart: unless-stopped
    volumes:
      - noosphere_redis_data:/data
    command: redis-server --save "" --appendonly no
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 5s

volumes:
  noosphere_postgres_data:
    name: noosphere_postgres_data
    driver: local
  noosphere_postgres_authorization:
    name: noosphere_postgres_authorization
    external: true
  noosphere_uploads:
    name: noosphere_uploads
    driver: local
  noosphere_redis_data:
    name: noosphere_redis_data
    driver: local
YAML
chmod 0600 "$compose_target"
fsync_installer_path "$compose_target"
fsync_installer_path "$(dirname "$compose_target")"

# Route only real source transitions through the controller. New installs keep
# a direct guard claim; already-complete installations need neither pre-step.
route_postgres_install_transition

# Whether the PostgreSQL image was already current or the controller just
# completed a real source transition, schema/bootstrap work still runs against
# the candidate with the application stopped. This is what upgrades released
# v1.11 data and is intentionally idempotent on rerun.
cd "$NOOSPHERE_HOME"
if docker inspect noosphere-openclaw-app >/dev/null 2>&1 &&
   [[ "$(docker inspect noosphere-openclaw-app --format '{{.State.Running}}')" == true ]]; then
  echo "Stopping Noosphere app before schema/bootstrap work..."
  docker stop --time 60 noosphere-openclaw-app >/dev/null
fi
echo "Starting Noosphere at ${APP_URL}..."
docker compose pull
docker compose up -d db redis
wait_for_container_healthy noosphere-openclaw-db 60
wait_for_container_healthy noosphere-openclaw-redis 30
verify_min_articles="$(
  capture_article_verification_floor noosphere-openclaw-db "$new_install_required"
)"

echo "Applying database schema and bootstrap data..."
# Run bootstrap to a temp file so we can check exit status separately.
# Admin/API credentials are passed through exported Compose variables.
BOOTSTRAP_TMP=$(mktemp)
BOOTSTRAP_EXIT=0
docker compose run --rm -T init < /dev/null > "$BOOTSTRAP_TMP" 2>&1 || BOOTSTRAP_EXIT=$?
if [ "$BOOTSTRAP_EXIT" -ne 0 ]; then
  echo "Bootstrap failed with exit code $BOOTSTRAP_EXIT:" >&2
  cat "$BOOTSTRAP_TMP" >&2
  echo "" >&2
  echo "Runtime config was preserved at $NOOSPHERE_HOME/.env; fix the error and rerun the installer to continue." >&2
  rm -f "$BOOTSTRAP_TMP"
  exit 1
fi
# Bootstrap writes JSON to stdout, mixed with Docker/Prisma status output.
# Extract it in one Node process instead of a grep|tail pipeline so set -euo
# pipefail cannot silently abort before we can print a useful diagnostic.
BOOTSTRAP_JSON=""
if ! BOOTSTRAP_JSON="$(extract_bootstrap_json "$BOOTSTRAP_TMP")"; then
  echo "Bootstrap produced no parseable JSON output. Full bootstrap log:" >&2
  cat "$BOOTSTRAP_TMP" >&2
  rm -f "$BOOTSTRAP_TMP"
  exit 1
fi
rm -f "$BOOTSTRAP_TMP"

echo "Bootstrap completed successfully."

if [[ "$new_install_required" == true ]]; then
  "$POSTGRES_SWITCH_SCRIPT" --record-new-install \
    --compose-file "$NOOSPHERE_HOME/docker-compose.yml" \
    --env-file "$NOOSPHERE_HOME/.env" \
    --db-container noosphere-openclaw-db \
    --app-container noosphere-openclaw-app \
    --backup-dir "$POSTGRES_BACKUP_DIR" \
    --defer-app-restart
fi

"$POSTGRES_SWITCH_SCRIPT" --authorize-writer \
  --compose-file "$NOOSPHERE_HOME/docker-compose.yml" \
  --env-file "$NOOSPHERE_HOME/.env" \
  --db-container noosphere-openclaw-db \
  --app-container noosphere-openclaw-app \
  --backup-dir "$POSTGRES_BACKUP_DIR"
docker compose up -d app
wait_for_container_healthy noosphere-openclaw-app 30
wait_for_http_health "$APP_URL" 60

NOOSPHERE_APP_URL="$APP_URL" \
NOOSPHERE_DB_CONTAINER=noosphere-openclaw-db \
NOOSPHERE_EXPECTED_DB_VOLUME=noosphere_postgres_data \
NOOSPHERE_EXPECTED_POSTGRES_IMAGE_MODE=candidate \
NOOSPHERE_MIN_ARTICLES="$verify_min_articles" \
NOOSPHERE_POSTGRES_EVIDENCE="$POSTGRES_BACKUP_DIR/noosphere_postgres_data.phase-a2b.json" \
  "$POSTGRES_VERIFY_SCRIPT"

INTEGRATION_API_KEY=$(select_scoped_integration_key "$EXISTING_INTEGRATION_API_KEY" default)
write_credentials_json "$NOOSPHERE_CREDENTIALS_FILE"

if [[ "$NOOSPHERE_INSTALL_OPENCLAW" == true ]]; then
  write_credentials_json "$SECRETS_FILE" true false

  echo "Installing OpenClaw plugin: ${PLUGIN_SPEC}"
  PLUGIN_INSTALL_ARGS=(plugins install "$PLUGIN_SPEC" --force)
  if [[ "$PLUGIN_SPEC" == npm:* ]]; then
    PLUGIN_INSTALL_ARGS+=(--pin)
  fi
  run_openclaw "${PLUGIN_INSTALL_ARGS[@]}"

  PATCH_FILE="$(mktemp)"
  cat > "$PATCH_FILE" <<JSON5
{
  secrets: {
    providers: {
      "${SECRET_PROVIDER_ID}": {
        source: "file",
        path: "${SECRETS_FILE}",
        mode: "json",
      },
    },
  },
  plugins: {
    entries: {
      "${PLUGIN_ID}": {
        enabled: true,
        config: {
          baseUrl: "${APP_URL}",
          apiKey: { source: "file", provider: "${SECRET_PROVIDER_ID}", id: "/apiKey" },
          autoRecall: true,
          autoProviders: ["noosphere"],
          maxInjectedMemories: 10,
          maxInjectedTokens: 1000,
          recallInjectionPosition: "system-prepend",
          autoRecallTimeoutMs: 5000,
        },
        hooks: {
          allowPromptInjection: true,
        },
      },
    },
  },
}
JSON5

  run_openclaw config patch --file "$PATCH_FILE"
  rm -f "$PATCH_FILE"

  if run_openclaw gateway status >/dev/null 2>&1; then
    echo "Restarting OpenClaw Gateway..."
    run_openclaw gateway restart
  else
    echo "OpenClaw Gateway is not running or status is unavailable; start/restart it when ready."
  fi
fi

cat <<DONE

╔══════════════════════════════════════════════════════════════════════╗
║                    Noosphere Setup Complete                           ║
╠══════════════════════════════════════════════════════════════════════╣
║                                                                      ║
║  Noosphere URL:    ${APP_URL}
║  Admin email:      admin@noosphere.local
║                                                                      ║
║  Credentials saved in: ${NOOSPHERE_CREDENTIALS_FILE}
║                                                                      ║
╚══════════════════════════════════════════════════════════════════════╝

Verify:
  curl -fsS ${APP_URL}/api/health
DONE

if [[ "$NOOSPHERE_INSTALL_OPENCLAW" == true ]]; then
  printf '  openclaw plugins inspect %s --runtime --json\n\n' "$PLUGIN_ID"
fi
if [[ "$NOOSPHERE_SHOW_CREDENTIALS" == true ]]; then
  printf 'Admin password: %s\nDefault WRITE API key: %s\nBootstrap ADMIN API key: %s\n\n' \
    "$ADMIN_PASSWORD" "$INTEGRATION_API_KEY" "$API_KEY"
else
  printf 'Credentials were not printed. Read the mode-0600 file above when needed.\n\n'
fi

# ── Per-Agent API Keys ──────────────────────────────────────────────────────────
#
# Each OpenClaw agent can have its own API key. The plugin auto-routes to the
# correct key based on the agent's ID. This avoids the shared-secrets-file problem
# where one agent overwrites another's key.
#
# HOW TO ADD A NEW AGENT KEY:
#
# 1. Create a key for the new agent via the Noosphere admin UI:
#    ${APP_URL}/wiki/admin/keys
#    (Admin login: admin@noosphere.local / ${ADMIN_PASSWORD})
#
# 2. Add the key as an environment variable in the OpenClaw gateway systemd unit.
#    The gateway must be restarted after each change:
#
#    mkdir -p ~/.config/systemd/user/openclaw-gateway.service.d/
#    cat >> ~/.config/systemd/user/openclaw-gateway.service.d/override.conf <<'EOF'
#    [Service]
#    Environment="NOOSPHERE_API_KEY_<AGENT_ID>=noo_newagentkey"
#    EOF
#    systemctl --user daemon-reload
#    systemctl --user restart openclaw-gateway
#
#    Replace <AGENT_ID> with the agent's OpenClaw ID in UPPERCASE,
#    hyphens replaced by underscores (e.g., agent "cyberlogis" → NOOSPHERE_API_KEY_CYBERLOGIS).
#
# KEY ROUTING PRIORITY (highest to lowest):
#   1. NOOSPHERE_API_KEY_<AGENT_ID>  (env var, per-agent, recommended)
#   2. apiKeys[agentId]              (config map, plain text)
#   3. apiKey / NOOSPHERE_API_KEY    (default fallback)
#
# CURRENT KEYS ON THIS HOST:
#   Run: grep NOOSPHERE_API_KEY /proc/$(pgrep -f openclaw.*gateway | head -1)/environ
#   Or:  openclaw noosphere status
}

if [[ ${BASH_SOURCE[0]} == "$0" ]]; then
  main "$@"
fi