compose-dev

#!/bin/sh
# Copyright © 2026 Gornskew Enterprises
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.  Distributed WITHOUT
# ANY WARRANTY; see <https://www.gnu.org/licenses/agpl-3.0.html>.

# compose-dev — POSIX sh; works with bash, dash, zsh, and macOS /bin/sh
# No bash arrays, no [[ ]], no shopt, no mapfile, no bash-specific constructs.

# =============================================================================
# COMPOSE FILE COLLECTION
#
# POSIX sh has no arrays. COMPOSE_FILES is a newline-delimited string of
# compose file paths, built once at startup. All docker compose invocations
# go through run_compose(), which reconstructs "-f file" pairs from it.
# =============================================================================

cd "${0%/*}"

export DOCKER_CONFIG="${HOME}/.docker"
SCRIPT_DIR="$(pwd)"

# THE SHELL'S SHARE OF A FORK'S DICTIONARY.  This script speaks the
# canonical ship register natively -- the ${BASILISK_VOCAB_*} fallbacks
# below ARE canon's words (muster titles, the stowaway designator,
# absence warnings).  A FORK never edits them here: its glossary.sexp
# :vocabulary emits generated/vocabulary.env at generation time, this
# sources it, and the shell speaks the fork's words instead.  Canon
# ships no glossary and so has no vocabulary.env.
[ -f "${SCRIPT_DIR}/generated/vocabulary.env" ] && \
    . "${SCRIPT_DIR}/generated/vocabulary.env"

# Collect compose files into newline-delimited COMPOSE_FILES.
# Order: base -> sorted non-dev overlays -> sorted dev overlays.
_collect_compose_files() {
    _base=""
    _others=""
    _devs=""

    [ -f "./docker-compose.yml" ] && _base="./docker-compose.yml"

    for _f in ./*.yml; do
        [ -f "$_f" ] || continue              # manual nullglob: skip if no match
        _n="${_f##*/}"
        [ "$_n" = "docker-compose.yml" ] && continue
        case "$_n" in
            *-dev-*) _devs="${_devs:+$_devs
}$_f" ;;
            *)       _others="${_others:+$_others
}$_f" ;;
        esac
    done

    [ -n "$_others" ] && _others="$(printf '%s\n' $_others | sort)"
    [ -n "$_devs"   ] && _devs="$(printf '%s\n' $_devs   | sort)"

    COMPOSE_FILES="${_base}${_others:+
$_others}${_devs:+
$_devs}"
}


# =============================================================================
# NO STANDALONE BOOTSTRAP.  CLONE THE REPO.
#
# There used to be a bootstrap_from_image() here: downloaded standalone with
# no clone, it would create a container from the skewed-emacs image and
# docker-cp docker-compose.yml, generate-env.sh and mcp/ back out of the
# repo snapshot baked inside it.
#
# Removed 2026-08-15 (Dave: "no more tricks with extracting yards from
# images").  It only ever existed because the stack machinery lived in the
# skewed-emacs repo and therefore in its image; once the yard is its own
# repo, the honest instruction is the obvious one:
#
#     git clone <basilisk>  &&  cd basilisk  &&  ./basilisk up
#
# That also removes a genuinely confusing coupling -- the image is a crew
# member's quarters, not a delivery vehicle for the shipyard -- and one
# whole class of staleness, where a bootstrapped directory kept running
# whatever the image happened to carry.
#
# Anything running from a checkout has docker-compose.yml beside it, so
# there is nothing to detect and nothing to fetch.
# =============================================================================

if [ ! -f "${SCRIPT_DIR}/docker-compose.yml" ]; then
    printf '%s\n' "[ERROR] No docker-compose.yml beside this script." >&2
    printf '%s\n' "        Basilisk runs from a clone of its own repo:" >&2
    printf '%s\n' "            git clone <basilisk> && cd basilisk && ./basilisk up" >&2
    exit 1
fi

_collect_compose_files

# =============================================================================
# run_compose ARGS...
#
# Invoke docker compose with all -f flags prepended. Each arg is individually
# single-quote-escaped before eval so args containing parens, spaces, etc. work.
# =============================================================================
_quote_arg() {
    printf "'"
    # Escape embedded single quotes as '\'' (close, literal ', reopen).
    # NB the quadruple backslash: the shell halves it, and sed needs \\
    # in the replacement to emit a literal backslash.  The old double-
    # backslash version emitted ''' (no backslash), which left an
    # unterminated quote whenever an argument contained a ' -- e.g. the
    # elisp sent by refresh_emacs_runtime_config ('ok, 'deferred), which
    # therefore always failed silently.
    printf '%s' "$1" | sed "s/'/'\\\\''/g"
    printf "'"
}

run_compose() {
    _rc_fargs=""
    while IFS= read -r _cf; do
        [ -n "$_cf" ] && _rc_fargs="$_rc_fargs -f $(_quote_arg "$_cf")"
    done << _FILELIST
$COMPOSE_FILES
_FILELIST

    _rc_caller=""
    for _a in "$@"; do
        _rc_caller="$_rc_caller $(_quote_arg "$_a")"
    done

    eval "$COMPOSE_CMD $_rc_fargs $_rc_caller"
}

# =============================================================================
# COLOR OUTPUT
# printf %b interprets \033 escapes; works in bash, dash, zsh, macOS sh.
# =============================================================================
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
MAGENTA='\033[0;35m'
NC='\033[0m'

log_info()    { printf "%b\n" "${BLUE}[INFO]${NC} $1"; }
log_success() { printf "%b\n" "${GREEN}[SUCCESS]${NC} $1"; }
log_warning() { printf "%b\n" "${YELLOW}[WARNING]${NC} $1"; }
log_error()   { printf "%b\n" "${RED}[ERROR]${NC} $1"; }

# =============================================================================
# PREFLIGHT
# =============================================================================
preflight_checks() {
    _pf_ok=true

    if ! command -v docker > /dev/null 2>&1; then
        echo ""
        echo "╔══════════════════════════════════════════════════════════════════╗"
        echo "║  ERROR: docker not found on PATH                                ║"
        echo "╠══════════════════════════════════════════════════════════════════╣"
        echo "║  Install Docker Desktop (macOS/Windows) or Docker Engine (Linux)║"
        echo "║  https://www.docker.com/products/docker-desktop/                ║"
        echo "╚══════════════════════════════════════════════════════════════════╝"
        echo ""
        _pf_ok=false
    elif ! docker info > /dev/null 2>&1; then
        echo ""
        echo "╔══════════════════════════════════════════════════════════════════╗"
        echo "║  ERROR: docker is installed but not running / not accessible    ║"
        echo "╠══════════════════════════════════════════════════════════════════╣"
        echo "║  macOS/Windows: start Docker Desktop and wait for green status  ║"
        echo "║  Linux:         sudo systemctl start docker                     ║"
        echo "╚══════════════════════════════════════════════════════════════════╝"
        echo ""
        _pf_ok=false
    fi

    [ "$_pf_ok" = "true" ]
}


# =============================================================================
# DOCKER COMPOSE DETECTION + FILE LIST DISPLAY
# =============================================================================
check_docker_compose() {
    if docker compose version > /dev/null 2>&1; then
        COMPOSE_CMD="docker compose"
    elif docker-compose version > /dev/null 2>&1; then
        COMPOSE_CMD="docker-compose"
    else
        log_error "Neither 'docker compose' nor 'docker-compose' is available"
        exit 1
    fi

    log_info "Using: $COMPOSE_CMD"
    log_info "Compose files (application order - later files override earlier):"

    while IFS= read -r _full_path; do
        [ -n "$_full_path" ] || continue
        _fn="${_full_path##*/}"
        case "$_fn" in
            docker-compose.yml)
                log_info "  - ${CYAN}${_fn}${NC}  ${BLUE}(base)${NC}" ;;
            *-dev-*)
                log_info "  - ${MAGENTA}${_fn}${NC}  ${YELLOW}(dev overlay)${NC}" ;;
            *)
                log_info "  - ${GREEN}${_fn}${NC}  ${GREEN}(added services)${NC}" ;;
        esac
    done << _FILELIST
$COMPOSE_FILES
_FILELIST
}

# =============================================================================
# ENVIRONMENT INIT
# =============================================================================
init_env() {
    PROJECTS_DIR="${PROJECTS_DIR:-${HOME}/projects}"
    export PROJECTS_DIR

    # stat flag differs: Linux -c '%g', macOS -f '%g'
    if [ -S "/var/run/docker.sock" ]; then
        DOCKER_GROUP_ID="$(stat -c '%g' /var/run/docker.sock 2>/dev/null \
            || stat -f '%g' /var/run/docker.sock 2>/dev/null \
            || echo 999)"
        export DOCKER_GROUP_ID
        log_info "Detected Docker group ID: $DOCKER_GROUP_ID"
    else
        export DOCKER_GROUP_ID=999
        log_warning "Docker socket not found, using default group ID: 999"
    fi

    if [ ! -d "$PROJECTS_DIR" ]; then
        log_info "Creating projects directory: $PROJECTS_DIR"
        mkdir -p "$PROJECTS_DIR"
    fi
}

ensure_env() {
    "${SCRIPT_DIR}/generate-env.sh"
}

# =============================================================================
# HELP
# =============================================================================
show_help() {
    cat << EOF
Basilisk — brings up the skewed-emacs stack: Emacs, the Gendl and GDL
engines, Cyclops and autoheal, crewed onto one network and validated.

'Basilisk' names the STACK.  'skewed-emacs' keeps meaning the Emacs
configuration and the image carrying it, which is one container in here.
This script answers to both names: ./basilisk and ./compose-dev are the
same file, so nothing that already says compose-dev breaks.  See
BASILISK.md.

USAGE:
    $0 <command> [options]

COMMANDS:
    up [service...]     Start services (default: all services)
    down               Stop and remove all services
    restart [service]  Restart service(s)
    stop [service]     Stop service(s) without removing
    logs [service]     Show logs for service(s)
    status             Show status of all services
    ps                 Show running containers
    emacs              Connect to Emacs via emacsclient
    pull               Pull missing images (use PULL_ALWAYS=1 to pull latest)
    clean              Remove containers, networks, and images
    init               Initialize environment (.env setup via generate-env.sh)
    install-shell-functions  Write eskew/egskew helpers to shell RC file(s)
    config             Show merged Docker Compose configuration

SERVICES:
    Services are defined in docker-compose.yml and any other .yml files
    in this directory (generated from basilisk.sexp, the editable SSoT).

VARIANT SWITCHES (skewed-emacs image; anywhere on the command line):
    --lite | --default | --tui | --gui | --full
    Set EMACS_IMAGE_VARIANT for this invocation (default: full for the
    dev stack).  E.g. '$0 up --default' spins up the slim
    snapshotting image; '$0 pull --full' pulls the kitchen sink.

EXAMPLES:
    $0 up                    # Start all services
    $0 up --pull             # Start all services and pull latest images
    $0 up --default          # Start with the slim default emacs image
    $0 up <service>          # Start only one service
    $0 up --pull <service>   # Start one service and pull latest image
    $0 logs <service>        # Show service logs
    PROJECTS_DIR=/path/to/projects $0 up   # Use a custom projects directory
    $0 emacs                 # Connect to Emacs interactively
    $0 config                # Show merged configuration

ENVIRONMENT:
    .env is generated by ./generate-env.sh; do not edit it directly.
    Additional .yml files in the current directory are automatically included.

    Key variables:
        PROJECTS_DIR    Projects directory to mount (default: ~/projects)

    Startup validation (see STARTUP VALIDATION section in this script):
        HEALTH_WAIT_SECS        per-service validation budget (default 30)
        HEALTH_BUDGET_<name>    per-service override (name sanitized to
                                [A-Za-z0-9_], e.g. HEALTH_BUDGET_gendl_ccl=45)
        HEALTH_MAX_RESTARTS     kill+recreate retries per service (default 2)
        HEALTH_POLL_SECS        probe cadence (default 2)

NETWORK:
    Services communicate via one Docker network per instance -- the
    ship himself, named by the yard (generate-env.sh mints into .ship,
    surfaced as DOCKER_NETWORK_NAME in .env)
    - From host: localhost:<host-port>
    - Inter-container: <service-hostname>:<container-port>

EOF
}

# =============================================================================
# SERVICE MANAGEMENT
# =============================================================================

# TEMPLATE SUBSTITUTION -- the yard rewrites the chief's standing
# orders (and any other templated fittings) from the current crew, on
# the way up.  templates/ arrives via a stack's ./install; crew.env is
# generated from the articles.  A ${BASILISK_POST_<POSTING>}
# placeholder resolves to the name of the first crew member standing
# that posting, and ${BASILISK_POST_<POSTING>_<FREQ>_PORT} to the
# aboard port of that member's named frequency -- so a rule written
# against a POSTING keeps working when the hand standing it is
# renamed or relieved.  One hand per posting for now (first declared
# wins); multiples are a known limitation, deliberately unhandled
# until the simple case has sailed.
substitute_templates() {
    [ -d "${SCRIPT_DIR}/templates" ] || return 0
    # The ledger arrives in layers: the base ship's generated/crew.env
    # (tracked yard output) plus any installed overlay ledger
    # (generated/<stack>-crew.env, carried in by that stack's
    # ./install under its own name -- an install must never overwrite
    # a tracked base file, or the clone goes permanently dirty and
    # blocks every future pull).  Later files win key-wise; one
    # overlay ledger is the expected case.
    _st_env=$(mktemp) || return 0
    _st_found=0
    for _st_e in "${SCRIPT_DIR}/generated/crew.env" "${SCRIPT_DIR}/generated/"*-crew.env; do
        [ -f "$_st_e" ] || continue
        cat "$_st_e" >> "$_st_env"
        _st_found=1
    done
    if [ "$_st_found" = 0 ]; then
        log_warning "templates/ present but no crew ledger in generated/; templates NOT rewritten"
        rm -f "$_st_env"
        return 0
    fi
    mkdir -p "${SCRIPT_DIR}/generated"
    for _st_t in "${SCRIPT_DIR}/templates/"*; do
        [ -f "$_st_t" ] || continue
        _st_out="${SCRIPT_DIR}/generated/$(basename "$_st_t")"
        awk 'NR==FNR {
                 line=$0; sub(/#.*/,"",line); eq=index(line,"=")
                 if (eq>1) { k=substr(line,1,eq-1); v=substr(line,eq+1)
                             gsub(/^[ \t]+|[ \t\r]+$/,"",k); env[k]=v }
                 next }
             { for (k in env) gsub("\\$\\{" k "\\}", env[k]); print }' \
            "$_st_env" "$_st_t" > "$_st_out"
        if grep -q '${BASILISK_POST_[A-Z0-9_]*}' "$_st_out"; then
            log_warning "$(basename "$_st_out") still names postings nobody stands: $(grep -o '${BASILISK_POST_[A-Z0-9_]*}' "$_st_out" | sort -u | tr '\n' ' ')"
        fi
        log_info "Rewrote $(basename "$_st_t") -> generated/$(basename "$_st_out") from the crew ledger"
    done
    rm -f "$_st_env"
}

start_services() {
    _ss_services="$*"
    init_env
    ensure_env
    substitute_templates

    # Ensure AI TUI auth placeholder files exist on host.
    # (Docker bind-mounts create directories for missing files, breaking TUIs.)
    for _auth_file in \
        "${HOME}/.claude/.credentials.json" \
        "${HOME}/.gemini/google_accounts.json" \
        "${HOME}/.gemini/oauth_creds.json" \
        "${HOME}/.codex/auth.json" \
        "${HOME}/.grok/auth.json"
    do
        if [ ! -f "$_auth_file" ]; then
            mkdir -p "$(dirname "$_auth_file")"
            touch "$_auth_file"
            log_info "Created placeholder: $_auth_file"
        fi
    done

    pull_images

    log_info "Starting services: ${_ss_services:-all}"
    # shellcheck disable=SC2086  (word-split intentional: service names)
    run_compose up -d $_ss_services

    # Started != validated: actively probe every healthchecked service
    # (kill + recreate hung-on-start containers, e.g. the CCL ASLR
    # wedge) BEFORE doing anything that depends on a running daemon.
    _ss_rc=0
    validate_services || _ss_rc=1

    # crew identities: per-container maintenance pass over the
    # just-validated fleet, same slot merge_mcp_configs already
    # occupies below -- order between the two doesn't matter, this
    # one just needs live containers
    mint_crew_identities

    # MCP merge runs after validation on purpose: a kill+recreate of
    # skewed-emacs would discard files copied into the container, and
    # a validated skewed-emacs means the daemon is provably ready --
    # no blind "waiting for emacs daemon" retry loop needed.
    merge_mcp_configs

    refresh_emacs_runtime_config

    return "$_ss_rc"
}

# =============================================================================
# HOST CLAUDE CODE MCP REGISTRY
#
# There are TWO MCP client registries on a dev box and only one of them was
# ever generated:
#
#   mcp/claude_desktop_config.json  -- Claude Desktop.  Generated output;
#                                      the merge above rewrites it, so it
#                                      follows the checkout automatically.
#   ~/.claude.json                  -- host-side Claude Code.  Hand-
#                                      maintained; nothing regenerated it.
#
# When the stack machinery moved from skewed-emacs to basilisk (2026-08-15)
# the Desktop config followed for free and ~/.claude.json did not.  It kept
# working only because the move was a COPY -- both mcp/mcp-exec files still
# existed.  Deleting the old checkout would have broken every host agent
# session, and not at deletion time: at the next session start, as servers
# that quietly fail to launch.  Checking one registry looks like checking
# both, which is exactly why this is now automatic.
#
# Deliberately conservative.  It only rewrites entries whose command already
# points at some */mcp/mcp-exec, it writes nothing when nothing is stale
# (the normal case), and it replaces the file atomically after a backup --
# that file also holds live Claude Code state, so it is never rewritten
# wholesale from a stale read.
# =============================================================================
refresh_host_claude_mcp() {
    _hcm_file="${HOME}/.claude.json"
    [ -f "$_hcm_file" ] || return 0

    _hcm_exec="${SCRIPT_DIR}/mcp/mcp-exec"
    [ -x "$_hcm_exec" ] || return 0

    if ! command -v python3 > /dev/null 2>&1; then
        log_warning "python3 not found; cannot check ~/.claude.json MCP paths"
        log_warning "If host Claude Code MCP stops resolving, point its"
        log_warning "mcpServers commands at ${_hcm_exec}"
        return 0
    fi

    _hcm_out=$(CLAUDE_JSON="$_hcm_file" MCP_EXEC="$_hcm_exec" python3 - <<'PYEOF'
import json, os, shutil, sys, tempfile

path   = os.environ["CLAUDE_JSON"]
target = os.environ["MCP_EXEC"]

try:
    with open(path) as fh:
        raw = fh.read()
    data = json.loads(raw)
except Exception as exc:                      # unreadable or mid-write
    print("SKIP %s" % exc)
    sys.exit(0)

servers = data.get("mcpServers")
if not isinstance(servers, dict):
    sys.exit(0)

changed = []
for name, cfg in servers.items():
    if not isinstance(cfg, dict):
        continue
    cmd = cfg.get("command")
    # Only ever retarget something that is already an mcp-exec launcher.
    if isinstance(cmd, str) and cmd.endswith("/mcp/mcp-exec") and cmd != target:
        cfg["command"] = target
        changed.append(name)

if not changed:
    sys.exit(0)                               # normal case: write nothing

shutil.copyfile(path, path + ".bak")
d = os.path.dirname(path) or "."
fd, tmp = tempfile.mkstemp(dir=d, prefix=".claude.json.")
try:
    with os.fdopen(fd, "w") as fh:
        json.dump(data, fh, indent=2)
        fh.write("\n")
    shutil.copymode(path, tmp)
    os.replace(tmp, path)                     # atomic
except Exception:
    try:
        os.unlink(tmp)
    except OSError:
        pass
    raise

print("CHANGED %d %s" % (len(changed), ",".join(sorted(changed))))
PYEOF
) || {
        log_warning "Could not update ~/.claude.json MCP paths"
        return 0
    }

    case "$_hcm_out" in
        CHANGED*)
            log_success "Host Claude Code MCP registry retargeted at ${_hcm_exec}"
            log_info "  ~/.claude.json updated (backup: ~/.claude.json.bak): ${_hcm_out#CHANGED }"
            log_info "  Takes effect in the NEXT agent session, not this one."
            ;;
        SKIP*)
            log_warning "Could not read ~/.claude.json (${_hcm_out#SKIP }); MCP paths unchecked"
            ;;
    esac
    return 0
}

stop_services() {
    log_info "Stopping all services"
    run_compose down
}

restart_services() {
    log_info "Restarting services: ${*:-all}"
    run_compose restart "$@"
    validate_services
    # a plain restart keeps the container's filesystem, so this is a
    # no-op for every service today (see the CREW IDENTITY MINTING
    # header comment) -- wired in now so the hook point already exists
    # once recreate-vs-restart semantics get worked out
    mint_crew_identities
}

# =============================================================================
# CREW IDENTITY MINTING (the Basilisk ship-and-crew conceit, framework-level)
#
# Mints a per-container identity -- NAME (random, species-flavored),
# SPECIES, ROLE -- and writes it into /tmp/skewed-crew-identity inside
# each running container, once.
#
# The two axes come from two different places, on purpose.  SPECIES is
# the IMAGE TYPE, read off Config.Image and never looked up.  ROLE
# comes from the POSTING -- the basilisk.post label, falling back to
# the hostname that basilisk.sexp already assigns.  So renaming a
# service in an overlay changes what it stands, not what it is, and
# swapping its image changes what it is, not what it stands.
#
# No schema change, every existing overlay (sally-stack, shelly-stack,
# ...) participates automatically, and any container this script has
# never heard of before still gets a generic crew identity with its
# image as its species.
#
# IDEMPOTENT BY DESIGN: skips any container whose identity file already
# exists.  A plain docker restart (same filesystem) therefore keeps
# its name; only a genuinely fresh/recreated container (new writable
# layer, no file) mints one.  Whether that is the full desired restart
# semantics is an open question (Dave, 2026-08-14) -- this is the
# conservative default until that gets worked through.
#
# Consumers: eyes-only-metrics.lisp's MY-IDENTITY and (for the Captain)
# EMACS-SAMPLE-ELISP both read this file in preference to minting their
# own name -- see apps/eyes-only source/metrics.lisp.
# =============================================================================

# SPECIES IS THE IMAGE TYPE -- repo:tag, DERIVED and never looked up
# (Dave, 2026-08-17).  There is no species table here any more, and no
# species registry anywhere: Basilisk does not adjudicate whether an
# image qualifies as a species, because the image simply IS one.
#
# The REGISTRY/NAMESPACE is stripped.  It is the image's home planet --
# its provenance -- and says nothing about what the image IS, so
# gornskew/gendl and someone else's gendl are the same species from
# different worlds.  (This replaces an older reading in which the
# genworks/gdl vs gornskew/gendl namespace was the signal behind the
# licensing tier.  That distinction is real, but it is provenance, and
# it now rides on the tag: :devo-enterprise-smp-licensed says it.)
#
# The TAG IS PART OF THE SPECIES.  gendl:devo-ccl and gendl:devo-sbcl
# are different species, which is precisely what the old glob table
# lost -- its */gendl:* arm dropped the tag and mustered both engineers
# alike.  Cute species names, for images we control, are issued as tags.
#
# Matched against the running container's own Config.Image (docker
# inspect), so this needs nothing from basilisk.sexp and works for a
# service this script has never named.
_crew_species_from_image() {
    _csi_ref="${1##*/}"         # drop registry/namespace; a registry
                                # port colon rides along with it
    _csi_ref="${_csi_ref%%@*}"  # a digest pin is not a species
    case "$_csi_ref" in
        "")  echo "unknown" ;;
        *:*) echo "$_csi_ref" ;;
        *)   echo "${_csi_ref}:latest" ;;   # implicit tag, made explicit
    esac
}

# Role comes from the POSTING, not the species (Dave, 2026-08-16).
#
# Deriving role from the image was only ever a guess made in the absence
# of a declared posting, and the canon makes it provably wrong: a
# Genworks GDL Engineer with Cyclops loaded into it stands in as the
# Pilot -- same species, different role -- so any species->role table
# mislabels it.  The hostname now DECLARES the posting, so the role is
# read rather than inferred.
#
# There is no longer a post->species table either (Dave, 2026-08-17).
# It ran backwards: what usually stands a post is a reasonable thing to
# know, but it is not how species is resolved.  Species comes off the
# image and nowhere else, so a post that cannot be recognized costs a
# stylish name and nothing more.
#
# Trailing -N is tolerated so a ship can carry more than one of a post
# (jr-eng-cyborg-2 is still an engineer).
#
# transporter-chief is the CURRENT name of the ingress posting (a
# reverse proxy receives; it never goes anywhere, so "pilot" described
# something the software does not do).  The pilot arm stays for
# containers created before the rename; both map to the same ROLE
# string, "pilot", because the role vocabulary reaches the eyes-only
# per-skin rank titles and renaming IT is a separate, still-open
# decision (Dave) -- do not rename the role here as a tidy-up.
_crew_role_for_posting() {
    case "$1" in
        captain|captain-[0-9]*)   echo "captain" ;;
        transporter-chief|transporter-chief-[0-9]*) echo "pilot" ;;
        pilot|pilot-[0-9]*)       echo "pilot" ;;
        medic|medic-[0-9]*)       echo "doctor" ;;
        communications-officer|communications-officer-[0-9]*) echo "comm" ;;
        comms|comms-[0-9]*)       echo "comm" ;;
        "${BASILISK_VOCAB_STOWAWAY_DESIGNATOR:-stowaway}"-*) echo "stowaway" ;;
        ships-engineer|ships-engineer-[0-9]*) echo "engineer" ;;
        guild-engineer|guild-engineer-[0-9]*) echo "engineer" ;;
        jr-eng-*|sr-eng-*|guild-*) echo "engineer" ;;
        *)                        echo "crew" ;;
    esac
}

# A basilisk.post label may carry a LIST (comma-joined): one crew
# member standing several posts.  No posting is primary and ordering
# carries no meaning, but ROLE= is single-valued legacy -- so take the
# first RECOGNIZED role scanning the list, without reading position as
# primacy.
_crew_role_for_postings() {
    _crp_role="crew"
    _crp_old_ifs=$IFS; IFS=','
    for _crp_p in $1; do
        _crp_r="$(_crew_role_for_posting "$_crp_p")"
        if [ "$_crp_r" != "crew" ]; then
            _crp_role="$_crp_r"
            break
        fi
    done
    IFS=$_crp_old_ifs
    echo "$_crp_role"
}

# MANNED/DRONE IS GONE FROM HERE, deliberately (Dave, 2026-08-17).
#
# It asked exactly one question -- is there a compiler aboard? -- and
# that is a CAPABILITY OF THE IMAGE, not a trait of a species, so it
# cannot be derived from a species table without guessing.  The image
# will answer for itself once our Dockerfiles carry OCI labels; they
# carry none today, so there is nothing to read yet and the field is
# not written at all rather than written as a guess.
#
# Nothing is lost in the meantime: MANNED= was computed, written and
# then read by nobody (verified 2026-08-17 -- the only sites that
# mentioned it were the four that produced it).  The lore distinction
# it encodes is real and load-bearing on pricing (a drone can be free
# or commercial, and the difference is priced), which is the argument
# for wiring it properly rather than for keeping a table that only
# ever approximated it.
#
# Do not reintroduce a species->manned case statement here.

# Name-pool syllables per species -- kept in sync BY HAND with
# eyes-only-metrics.lisp's *CREW-NAME-POOLS* (that Lisp copy is now the
# fallback path only; this shell copy is authoritative whenever
# compose-dev is what started the stack).
#
# THIS IS A STYLE TABLE, NOT A SPECIES REGISTRY.  It grants no
# membership and gates nothing: a species absent from it is a perfectly
# good species that draws from the unknown pool, which costs a stylish
# name and nothing else.  Defaults are fine; registries are not.
#
# Keyed on repo:tag and MATCHED MOST-SPECIFIC-FIRST, which is how the
# tag earns its keep: gendl:devo-ccl and gendl:devo-sbcl are different
# species and now sound like it, instead of both mustering out of the
# one gendl pool as they did until 2026-08-17.  Order matters in both
# case statements -- *non-smp* must precede *smp*, which would
# otherwise swallow it.
#
# COMMS (eyes-only) is here before its container is: Eyes Only has no
# image yet, so nothing mints one today, but it lands the moment the
# board ships as a binary with a :post :comms.  Until 2026-08-17 it
# would have fallen through to the unknown pool and sounded like no
# one.  The Comms character -- lilting and nasal, resolving on a hum,
# so a name trails off rather than stopping -- is deliberately the one
# corner of the sonic space the other
# pools leave empty: captain consonant-heavy, gendl liquid, gdl
# English-gentry, cyclops clipped and sibilant, autoheal vocalic.
_crew_onsets_for() {
    case "$1" in
        skewed-emacs:*) echo 'Bl Gr Thr Kro Zar Vex Mog Drel' ;;
        cyclops:*)      echo 'Bl Zh Vek Skr Yor Tsa Kli Dro' ;;
        gendl:*sbcl*)   echo 'Vas Ael Ion Cyr Tha Mor Zel Ryn' ;;
        gendl:*)        echo 'Ka Lis Par Quo Sem Tel Nym Ori' ;;
        gdl:*non-smp*)  echo 'Ad Bex Cor Dal Enn Fir Gal Hux' ;;
        gdl:*)          echo 'Ost Ven Kal Rhe Sig Tor Wex Yar' ;;
        autoheal:*)     echo 'Om Sal Vel Lum Mir Ana Eir Thea' ;;
        eyes-only:*)    echo 'Nil Myr Len Vael Sion Nyel Lir Nao' ;;
        *)              echo 'X Yz Qm' ;;
    esac
}
_crew_finals_for() {
    case "$1" in
        skewed-emacs:*) echo 'org arn und ath esh ork ilk uz' ;;
        cyclops:*)      echo 'ej ix osk arr unn eth yx oa' ;;
        gendl:*sbcl*)   echo 'ien uur eos aal ymn ore ith yss' ;;
        gendl:*)        echo 'da per lon ta mir vex is und' ;;
        gdl:*non-smp*)  echo 'mand ton dry well berg worth field ston' ;;
        gdl:*)          echo 'holm gate forge crest march stead vale bury' ;;
        autoheal:*)     echo 'a une is oon ara elle ios em' ;;
        eyes-only:*)    echo 'am een ion um ain oem un yn' ;;
        *)              echo 'ar il ot' ;;
    esac
}

# Random 1-based pick from a space-separated word list ($1).  No bash
# arrays/$RANDOM (dash has neither) -- /dev/urandom via od, same
# portability posture as the rest of this script.
_crew_pick() {
    set -- $1
    _cp_n=$#
    _cp_r=$(od -An -N2 -tu2 /dev/urandom | tr -d ' ')
    _cp_i=$(( (_cp_r % _cp_n) + 1 ))
    eval "echo \${$_cp_i}"
}

# One species-flavored name, unique against every name minted so far
# THIS RUN (_crew_minted_names).  20 collisions -> numeral-disambiguated
# (mirrors eyes-only-metrics.lisp's MINT-CREW-NAME).
_crew_unique_name() {
    _cun_species="$1"
    _cun_tries=0
    while :; do
        _cun_name="$(_crew_pick "$(_crew_onsets_for "$_cun_species")")$(_crew_pick "$(_crew_finals_for "$_cun_species")")"
        case " ${_crew_minted_names} " in
            *" ${_cun_name} "*)
                _cun_tries=$((_cun_tries + 1))
                [ $_cun_tries -ge 20 ] && {
                    _cun_name="${_cun_name}-$(od -An -N1 -tu1 /dev/urandom | tr -d ' ')"
                    break
                }
                continue
                ;;
            *) break ;;
        esac
    done
    # set a result var, NOT echo+$(...) -- a command-substitution call
    # would run this function in a SUBSHELL, silently discarding its
    # write to _crew_minted_names (caught empirically 2026-08-14: two
    # calls minted the same name back to back).  Callers read
    # $_crew_unique_name_result after calling this directly.
    _crew_minted_names="${_crew_minted_names:+$_crew_minted_names }${_cun_name}"
    _crew_unique_name_result="$_cun_name"
}

mint_crew_identities() {
    _ci_ids="$(run_compose ps -q 2>/dev/null)"
    [ -n "$_ci_ids" ] || return 0

    _crew_minted_names=""
    for _ci_id in $_ci_ids; do
        _ci_name="$(docker inspect --format "{{.Name}}" "$_ci_id" 2>/dev/null)" || continue
        _ci_name="${_ci_name#/}"

        if docker exec "$_ci_name" test -f /tmp/skewed-crew-identity 2>/dev/null; then
            continue   # already identified -- filesystem survived, keep the name
        fi

_ci_image="$(docker inspect --format \
            "{{.Config.Image}}" \
            "$_ci_id" 2>/dev/null)"

        # Posting is the container's hostname, which the generator set
        # from the SSoT :name.  Fall back to the container name with any
        # BASILISK_PREFIX stripped, for containers created before this.
        _ci_posting="$(docker inspect --format "{{.Config.Hostname}}" \
            "$_ci_id" 2>/dev/null)"
        [ -n "$_ci_posting" ] || _ci_posting="${_ci_name#${BASILISK_PREFIX:-}}"

        # Species is the image type, full stop -- no label to consult,
        # no post default to fall back to, nothing to resolve between
        # (Dave, 2026-08-17).  The old three-step chain also had an
        # ordering bug that dies with it: its post-default arm ran
        # against the HOSTNAME-derived posting, because the
        # basilisk.post label override below had not happened yet.
        _ci_species="$(_crew_species_from_image "$_ci_image")"

        # Post: the declared label wins, the hostname is the
        # fallback for containers created before labels existed.
        _ci_post="$(docker inspect \
            --format '{{index .Config.Labels "basilisk.post"}}' \
            "$_ci_id" 2>/dev/null)"
        [ -n "$_ci_post" ] && _ci_posting="$_ci_post"

        _ci_role="$(_crew_role_for_postings "$_ci_posting")"
        _crew_unique_name "$_ci_species"
        _ci_mint_name="$_crew_unique_name_result"

        # NAME= stays FIRST: every reader is key-based except
        # skewed-emacs's dashboard, which reads line 1 and requires the
        # NAME= prefix.  MANNED= used to be appended last and is no
        # longer written at all -- see the note where its table was;
        # every reader scans for its own keys, so dropping it is
        # backward-compatible the same way adding it was.
        if docker exec "$_ci_name" sh -c \
            "printf 'NAME=%s\nSPECIES=%s\nROLE=%s\n' '$_ci_mint_name' '$_ci_species' '$_ci_role' > /tmp/skewed-crew-identity" \
            2>/dev/null
        then
            log_success "  ${_ci_name}: crew identity minted -- ${_ci_mint_name} (${_ci_role}, ${_ci_species})"
        else
            log_warning "  ${_ci_name}: could not write crew identity (no shell/writable rootfs?)"
        fi
    done
}


# =============================================================================
# MCP CONFIG MERGE
#
# Writes merged MCP config files inside the skewed-emacs container and
# updates /home/emacs-user/.codex/config.toml and ~/.grok/config.toml.
# Runs AFTER validate_services: overlay copies into a container that
# validation might still kill+recreate would be lost, and a validated
# skewed-emacs (its lisply-ping healthcheck is served by the emacs
# daemon itself) proves the daemon is ready -- the merge runs exactly
# once, event-driven, replacing the old 5x2s blind retry loop.
# =============================================================================
merge_mcp_configs() {
    log_info "Preparing MCP configurations (JSON + TOML)..."

    case " ${VALIDATED_OK:-} " in
        *" captain "*) ;;
        *)
            # The Captain was not validated this run (single-service up,
            # failed validation, or already running from before): probe the
            # daemon once directly instead of looping blind.
            if ! run_compose exec -T captain emacsclient --eval t \
                > /dev/null 2>&1
            then
                log_warning "Captain daemon not available; skipping MCP config merge"
                return 1
            fi
            ;;
    esac

    # Lite-variant images do not ship ~/.codex and ~/.grok, so docker
    # creates those file-mount parent dirs ROOT-OWNED at container
    # create time (a recreate reintroduces them; host-side chown cannot
    # reach container-fs dirs).  The merge writes config.toml into both,
    # so repair ownership first; harmless no-op on full images.
    run_compose exec -T -u root captain sh -c \
        "chown -R emacs-user /home/emacs-user/.codex /home/emacs-user/.grok" \
        > /dev/null 2>&1 || true

    # Step 1: Stage the YARD's mcp/ into the Captain.
    #
    # mcp/ left the skewed-emacs repo when it was spun off to basilisk,
    # so the image no longer carries /home/emacs-user/skewed-emacs/mcp
    # and neither the base configs nor merge-mcp-configs.el are aboard.
    # This used to copy overlays into that now-absent directory with
    # `|| true`, so every copy failed silently and the merge then died
    # on a missing load-file -- surfacing only as "daemon answered but
    # merge errored" (found on a real deploy, 2026-08-16).  The yard owns
    # these files now, so the yard hands them over at up-time.
    #
    # Same failure shape as the mcp/entrypoint.sh incident: a split moved
    # files by concept without checking every consumer.
    _mcp_stage="/tmp/basilisk-mcp"
    run_compose exec -T captain mkdir -p "$_mcp_stage" > /dev/null 2>&1 || {
        log_warning "could not create $_mcp_stage in the Captain; skipping MCP merge"
        return 1
    }

    for _mcpfile in \
        "${SCRIPT_DIR}/mcp/merge-mcp-configs.el" \
        "${SCRIPT_DIR}/mcp/mcp-container.json" \
        "${SCRIPT_DIR}/mcp/mcp-windows.json" \
        "${SCRIPT_DIR}/mcp/mcp.toml" \
        "${SCRIPT_DIR}/mcp/"*-mcp-windows.json \
        "${SCRIPT_DIR}/mcp/"*-mcp-container.json \
        "${SCRIPT_DIR}/mcp/"*-mcp.toml
    do
        [ -f "$_mcpfile" ] || continue
        log_info "Staging: $(basename "$_mcpfile")"
        run_compose cp "$_mcpfile" "captain:${_mcp_stage}/" 2>/dev/null \
            || log_warning "  could not stage $(basename "$_mcpfile")"
    done

    # Step 1b: Copy overlay services-generated Emacs files, PLUS
    # services-discovery.el -- the discovery/merge logic and the
    # generated files are a matched pair (sparse overlay entries rely
    # on key-wise merging in discovery).  Syncing one without the
    # other skews them when the running image predates a discovery
    # change (bit us 2026-08-09: gendl-ccl vanished from the dashboard
    # Swank list on a stale image + fresh sparse overlay).
    # Sources differ on purpose.  services-generated.el files are YARD
    # OUTPUT and live in generated/; services-discovery.el is Emacs
    # CONFIGURATION and stays in the Captain's dot-files tree.  That split
    # is the whole point of the basilisk move -- see MIGRATION.md.
    #
    # The glob is *services-generated.el, NOT *-services-generated.el, and
    # the missing dash is load-bearing.  It has to match the unprefixed
    # BASE file as well as the <host>-stack- prefixed overlays.  Until the
    # rip, the base file reached the container baked into the skewed-emacs
    # image, so only overlays needed copying; now that the yard has left
    # that repo the image no longer carries it, and a dashed glob would
    # silently ship a container that knows about cyclops and the GDL units
    # but not about skewed-emacs, gendl-sbcl or autoheal.
    for _overlay in "${SCRIPT_DIR}/generated/"*services-generated.el \
                    "${SCRIPT_DIR}/dot-files/emacs.d/etc/services-discovery.el"; do
        [ -f "$_overlay" ] || continue
        log_info "Copying overlay: $(basename "$_overlay")"
        run_compose cp "$_overlay" \
            captain:/home/emacs-user/skewed-emacs/dot-files/emacs.d/etc/ 2>/dev/null || true
    done

    # Step 2: Merge inside container -- one shot; the daemon is ready.
    if run_compose exec -T captain emacsclient --eval \
        "(progn (setenv \"SKEWED_CLONE_PATH\" \"${SCRIPT_DIR}\")
                (load-file \"${_mcp_stage}/merge-mcp-configs.el\")
                (skewed-merge-all-mcp-configs \"${_mcp_stage}\"))" \
        > /dev/null 2>&1
    then
        log_success "MCP configurations merged for container CLI, Windows, Codex, and Grok"

        # Copy the platform-appropriate Claude Desktop config back to the
        # host clone (regression fix: the pre-POSIX compose-dev did this).
        # WSL hosts get the wsl-wrapped config; Linux/macOS get the native one.
        if grep -qi microsoft /proc/version 2>/dev/null; then
            _cdc_src="/tmp/merged-mcp-windows.json"
        else
            _cdc_src="/tmp/merged-mcp-host.json"
        fi
        # Claude CODE's registry is a different file from Claude
        # Desktop's, and cannot be copied over: ~/.claude.json carries
        # machineID, userID, seen-notification state and migration flags
        # alongside mcpServers.  So the yard also drops the host-form
        # config here, and mcp/install-claude-code-config splices just
        # its mcpServers key into ~/.claude.json.  Always the host form,
        # never the windows one -- Claude Code runs inside WSL, where
        # the wsl.exe wrapper the Desktop config needs would be wrong.
        run_compose cp "captain:/tmp/merged-mcp-host.json" \
            "${SCRIPT_DIR}/mcp/claude-code-mcp.json" 2>/dev/null \
            || log_warning "could not stage mcp/claude-code-mcp.json"

        if run_compose cp "captain:${_cdc_src}" \
            "${SCRIPT_DIR}/mcp/claude_desktop_config.json" 2>/dev/null; then
            log_success "Claude Desktop config ready: mcp/claude_desktop_config.json (see docs/CLAUDE_DESKTOP.md)"
        else
            log_warning "Could not copy Claude Desktop config from container"
            log_warning "(an older skewed-emacs image may not generate ${_cdc_src};"
            log_warning " try './compose-dev up --pull' to fetch the latest image)"
        fi

        refresh_host_claude_mcp
    else
        log_warning "MCP configuration merge failed (daemon answered but merge errored)"
        log_warning "Retry with: ./compose-dev up"
        return 1
    fi
}

# =============================================================================
# STARTUP VALIDATION ("container started" != "service validated")
#
# CCL occasionally loses its ASLR dice roll at startup ("exception 11" /
# "bad frame in rt_sigreturn", upstream Clozure/ccl#85): the process
# does not exit -- it hangs in the CCL kernel debugger -- so
# `restart: unless-stopped` never fires and the container sits there
# "running" while never becoming healthy.  The generated healthchecks
# have long intervals (gendl-ccl: 72s x 3 retries), so docker/autoheal
# take minutes to notice; a gendl container that is going to come up
# does so well within ~30s.  So compose-dev owns start-time validation
# itself (autoheal keeps steady-state duty):
#
#   - Each healthchecked container is actively probed every few seconds
#     by running its own compose-declared healthcheck test via docker
#     exec -- no per-service knowledge is hardcoded here, and docker's
#     slow health interval stops mattering at startup.
#   - A container that exhausts its budget unvalidated is KILLED
#     (SIGKILL: the wedged CCL debugger is SIGTERM-immune) and
#     RECREATED -- a fresh exec re-rolls the ASLR dice; a hung-at-start
#     container holds no state worth preserving.
#   - Retries are capped; then we fail LOUDLY with a nonzero exit so a
#     systemd oneshot unit shows the failure.
#
# Tunables (env):
#   HEALTH_WAIT_SECS        per-service validation budget (default 30)
#   HEALTH_BUDGET_<name>    per-service override, name sanitized to
#                           [A-Za-z0-9_], e.g. HEALTH_BUDGET_gendl_ccl=45
#   HEALTH_MAX_RESTARTS     kill+recreate budget per service (default 2)
#   HEALTH_POLL_SECS        probe cadence (default 2)
#   VALIDATE_PROBE_TIMEOUT  in-container timeout per probe (default 5)
#
# Results are exported in VALIDATED_OK / VALIDATED_FAILED (space-
# separated container names) for later phases (e.g. the MCP merge).
# =============================================================================
_vs_sanitize() {
    printf '%s' "$1" | tr -c 'a-zA-Z0-9' '_'
}

# Run one active probe of a container: its own declared healthcheck
# test via docker exec, wrapped in an in-container timeout (probe
# lesson from the rt_sigreturn brief: put the timeout INSIDE the
# container).  Falls back to docker's health status when the container
# lacks timeout(1) or the test could not be extracted.
_vs_probe() {
    _vp_san="$(_vs_sanitize "$1")"
    eval "_vp_cmd=\${_vs_probe_cmd_${_vp_san}:-}"
    if [ -n "$_vp_cmd" ]; then
        docker exec "$1" sh -c \
            "timeout -s KILL ${VALIDATE_PROBE_TIMEOUT:-5} $_vp_cmd" \
            > /dev/null 2>&1
        _vp_rc=$?
        [ "$_vp_rc" -eq 0 ] && return 0
        if [ "$_vp_rc" -eq 127 ]; then
            # timeout(1) missing in this container: retry bare.
            docker exec "$1" sh -c "$_vp_cmd" > /dev/null 2>&1 && return 0
        fi
    fi
    [ "$(docker inspect --format \
        '{{if .State.Health}}{{.State.Health.Status}}{{else}}unknown{{end}}' \
        "$1" 2>/dev/null)" = "healthy" ]
}

# Kill + recreate one container.  SIGKILL, not SIGTERM: a wedged CCL
# sits in its kernel debugger, which ignores SIGTERM.  Recreate (not
# restart) also re-resolves mount sources and image config.
_vs_recreate() {
    docker kill "$1" > /dev/null 2>&1
    if ! run_compose up -d --force-recreate --no-deps "$2" > /dev/null 2>&1; then
        log_error "  ${1}: recreate failed (docker compose up --force-recreate ${2})"
    fi
}

# =============================================================================
# CREW MUSTER -- what the articles expect vs what is actually aboard
#
# Nothing ever CHECKED the ship's complement at runtime, so a ship could
# report every service healthy while serving nothing at all.  Sally did
# exactly that on 2026-08-15 -- validation passed, five containers
# green, and the ingress publishing a dev port instead of :80, which no
# layer mentioned because no layer was looking.
#
# So this prints the manifest every time: post, service, and the ports it
# actually publishes.  Making the ingress port visible at startup is most
# of the value; a wrong one is obvious the moment you can see it.
# =============================================================================
crew_muster() {
    _cm_services=$(run_compose config --services 2>/dev/null | tr -d '\r' | sort)
    [ -n "$_cm_services" ] || return 0

    log_info "Crew muster:"
    _cm_have_pilot=0
    for _cm_svc in $_cm_services; do
        _cm_cname="${BASILISK_PREFIX:-}${_cm_svc}"
        # Roles come from the DECLARED posting label when there is one
        # (a comma list -- no posting primary), from the service name
        # for containers created before labels, via the SAME
        # derivation minting uses (two tables, one truth: a private
        # species->role copy here silently mustered every renamed post
        # as "Crew" on a real deploy, 2026-08-16).  A container with
        # NO posting at all is a STOWAWAY: a species specimen aboard,
        # comprehended like anyone else, assigned nothing.
        _cm_posts="$(docker inspect --format \
            '{{index .Config.Labels "basilisk.post"}}' \
            "$_cm_cname" 2>/dev/null)"
        if [ -n "$_cm_posts" ]; then
            _cm_role="$(_crew_role_for_postings "$_cm_posts")"
        else
            _cm_role="$(_crew_role_for_posting "$_cm_svc")"
            [ "$_cm_role" = "crew" ] && _cm_role="stowaway"
        fi
        # Display titles: canon's words as defaults, a fork's via the
        # sourced vocabulary.
        case "$_cm_role" in
            captain)  _cm_post="${BASILISK_VOCAB_TITLE_CAPTAIN:-Captain}" ;;
            pilot)    _cm_post="${BASILISK_VOCAB_TITLE_PILOT:-T-Chief}" ; _cm_have_pilot=1 ;;
            engineer) _cm_post="${BASILISK_VOCAB_TITLE_ENGINEER:-Engineer}" ;;
            comm)     _cm_post="${BASILISK_VOCAB_TITLE_COMM:-Comm}" ;;
            doctor)   _cm_post="${BASILISK_VOCAB_TITLE_DOCTOR:-Medic}" ;;
            stowaway) _cm_post="${BASILISK_VOCAB_TITLE_STOWAWAY:-Stowaway}" ;;
            *)        _cm_post="${BASILISK_VOCAB_TITLE_CREW:-Crew}" ;;
        esac
        _cm_ports=$(docker ps --filter "name=^${BASILISK_PREFIX:-}${_cm_svc}\$" \
                              --format '{{.Ports}}' 2>/dev/null \
                        | tr ',' '\n' | sed -n 's/.*0\.0\.0\.0:\([0-9]*\)->\([0-9]*\).*/\1->\2/p' \
                        | sort -u | tr '\n' ' ')
        printf '  %-8s %-24s %s\n' "$_cm_post" "$_cm_svc" "${_cm_ports:-(no published ports)}"

        # REQUIREMENTS vs CAPABILITIES (Dave, 2026-08-17).  A posting
        # states its requirements (basilisk.requires, emitted by the
        # yard); the species states its capabilities in its own image
        # manifest (basilisk.capabilities label) -- the SSoT for what an
        # image can do.  A manifest with no capability list cannot be
        # verified and says so quietly; a manifest that HAS one and is
        # missing a required capability is a loud warning.
        # One crew member may stand several posts (basilisk.post is a
        # comma list; no posting is primary).  Print the full list
        # whenever there is more than the name already says.
        case "$_cm_posts" in
            *,*) log_info "    stands: ${_cm_posts}" ;;
        esac
        # REQUIREMENTS vs CAPABILITIES: basilisk.requires unions the
        # qualifications of every post stood (emitted by the yard from
        # the :postings tables); basilisk.capabilities on the IMAGE
        # manifest is the SSoT for what the species can do.  A missing
        # capability WARNS and never errors -- the ability may come
        # aboard by arrangement (a services-init hook, at boot or
        # later), which the manifest cannot know.
        _cm_requires="$(docker inspect --format \
            '{{index .Config.Labels "basilisk.requires"}}' \
            "$_cm_cname" 2>/dev/null)"
        if [ -n "$_cm_requires" ]; then
            _cm_img="$(docker inspect --format '{{.Config.Image}}' \
                "$_cm_cname" 2>/dev/null)"
            _cm_caps="$(docker image inspect --format \
                '{{index .Config.Labels "basilisk.capabilities"}}' \
                "$_cm_img" 2>/dev/null)"
            if [ -z "$_cm_caps" ]; then
                log_info "    requires [${_cm_requires}]; species manifest carries no capability list (cannot verify)"
            else
                _cm_old_ifs=$IFS; IFS=','
                for _cm_req in $_cm_requires; do
                    case ",$_cm_caps," in
                        *",$_cm_req,"*) ;;
                        *) log_warning "    ${_cm_svc}: stands a post requiring \"${_cm_req}\" but species ${_cm_img} does not list it (arranged aboard?)" ;;
                    esac
                done
                IFS=$_cm_old_ifs
            fi
        fi
    done

    # An absent post is legal -- every post is optional, :captain included --
    # but it has a consequence worth saying out loud.
    if [ "$_cm_have_pilot" -eq 0 ]; then
        log_warning "${BASILISK_VOCAB_NO_INGRESS_WARNING:-no Transporter Chief aboard: nothing fronts HTTP; publish ports directly}"
        log_warning "  (if this ship is meant to have one, its overlay is missing:"
        log_warning "   run <host>-stack/install, which copies <host>-stack-compose.yml here)"
    fi
}

validate_services() {
    _vs_budget_default="${HEALTH_WAIT_SECS:-30}"
    _vs_retries_max="${HEALTH_MAX_RESTARTS:-2}"
    _vs_poll="${HEALTH_POLL_SECS:-2}"
    VALIDATED_OK=""
    VALIDATED_FAILED=""

    _vs_ids="$(run_compose ps -q 2>/dev/null)"
    [ -n "$_vs_ids" ] || { log_warning "No running containers to validate"; return 0; }

    # Build the watch list: containers that declare a usable healthcheck.
    _vs_watched=""
    for _vs_id in $_vs_ids; do
        _vs_name="$(docker inspect --format '{{.Name}}' "$_vs_id" 2>/dev/null)" || continue
        _vs_name="${_vs_name#/}"
        _vs_test="$(docker inspect --format \
            '{{if .Config.Healthcheck}}{{join .Config.Healthcheck.Test " "}}{{end}}' \
            "$_vs_id" 2>/dev/null)"
        case "$_vs_test" in
            ""|NONE|"NONE "*)
                log_info "  ${_vs_name}: started (no healthcheck; not validated)"
                continue
                ;;
        esac
        _vs_svc="$(docker inspect --format \
            '{{index .Config.Labels "com.docker.compose.service"}}' \
            "$_vs_id" 2>/dev/null)"
        [ -n "$_vs_svc" ] || _vs_svc="$_vs_name"
        _vs_san="$(_vs_sanitize "$_vs_name")"
        _vs_probe_tmp=""
        case "$_vs_test" in
            "CMD-SHELL "*) _vs_probe_tmp="${_vs_test#CMD-SHELL }" ;;
            "CMD "*)       _vs_probe_tmp="${_vs_test#CMD }" ;;
        esac
        eval "_vs_svc_${_vs_san}=\$_vs_svc"
        eval "_vs_probe_cmd_${_vs_san}=\$_vs_probe_tmp"
        eval "_vs_budget_${_vs_san}=\${HEALTH_BUDGET_${_vs_san}:-\$_vs_budget_default}"
        eval "_vs_state_${_vs_san}=pending"
        eval "_vs_elapsed_${_vs_san}=0"
        eval "_vs_tries_${_vs_san}=0"
        _vs_watched="${_vs_watched:+$_vs_watched }$_vs_name"
    done
    [ -n "$_vs_watched" ] || return 0

    log_info "Validating services (probe every ${_vs_poll}s; kill+recreate on hung start):"
    for _vs_name in $_vs_watched; do
        _vs_san="$(_vs_sanitize "$_vs_name")"
        eval "_vs_budget=\$_vs_budget_${_vs_san}"
        log_info "  ${_vs_name}: budget ${_vs_budget}s, retries ${_vs_retries_max}"
    done

    _vs_total=0
    while :; do
        _vs_pending=0
        for _vs_name in $_vs_watched; do
            _vs_san="$(_vs_sanitize "$_vs_name")"
            eval "_vs_state=\$_vs_state_${_vs_san}"
            [ "$_vs_state" = "pending" ] || continue

            if _vs_probe "$_vs_name"; then
                eval "_vs_tries=\$_vs_tries_${_vs_san}"
                if [ "$_vs_tries" -gt 0 ]; then
                    log_success "  ${_vs_name}: validated at ${_vs_total}s (after ${_vs_tries} kill+recreate)"
                else
                    log_success "  ${_vs_name}: validated at ${_vs_total}s"
                fi
                eval "_vs_state_${_vs_san}=ok"
                VALIDATED_OK="${VALIDATED_OK:+$VALIDATED_OK }$_vs_name"
                continue
            fi

            eval "_vs_elapsed=\$_vs_elapsed_${_vs_san}"
            eval "_vs_budget=\$_vs_budget_${_vs_san}"
            if [ "$_vs_elapsed" -ge "$_vs_budget" ]; then
                eval "_vs_tries=\$_vs_tries_${_vs_san}"
                if [ "$_vs_tries" -lt "$_vs_retries_max" ]; then
                    _vs_tries=$((_vs_tries + 1))
                    eval "_vs_tries_${_vs_san}=\$_vs_tries"
                    eval "_vs_svc=\$_vs_svc_${_vs_san}"
                    log_warning "  ${_vs_name}: not validated after ${_vs_budget}s (hung start?) -- kill + recreate (${_vs_tries}/${_vs_retries_max})"
                    _vs_recreate "$_vs_name" "$_vs_svc"
                    eval "_vs_elapsed_${_vs_san}=0"
                else
                    log_error "  ${_vs_name}: FAILED: still not validated after ${_vs_retries_max} kill+recreate retries"
                    eval "_vs_state_${_vs_san}=failed"
                    VALIDATED_FAILED="${VALIDATED_FAILED:+$VALIDATED_FAILED }$_vs_name"
                    continue
                fi
            else
                eval "_vs_elapsed_${_vs_san}=$((_vs_elapsed + _vs_poll))"
            fi
            _vs_pending=1
        done

        [ "$_vs_pending" -eq 0 ] && break
        sleep "$_vs_poll"
        _vs_total=$((_vs_total + _vs_poll))
    done

    if [ -z "$VALIDATED_FAILED" ]; then
        log_success "All services validated in ${_vs_total}s"
        crew_muster
        return 0
    fi

    log_error "Validation FAILED for: ${VALIDATED_FAILED}"
    for _vs_name in $VALIDATED_FAILED; do
        log_error "--- last log lines from ${_vs_name}:"
        docker logs --tail 5 "$_vs_name" 2>&1 | sed 's/^/    /'
        case "$_vs_name" in
            gendl-*|genworks-*)
                log_error "    (CCL ASLR wedge? check host kernel log for 'bad frame in rt_sigreturn' -- upstream Clozure/ccl#85)"
                ;;
        esac
    done
    log_error "autoheal (if running) will keep retrying; investigate with: docker logs <name>"
    return 1
}

show_logs() {
    run_compose logs -f "$@"
}

show_status() {
    log_info "Service status:"
    run_compose ps
}

connect_emacs() {
    log_info "Connecting to Emacs via emacsclient"
    run_compose exec captain emacsclient -t
}

pull_images() {
    if [ -n "${NO_PULL}" ]; then
        log_info "Skipping pull (NO_PULL set)"
        return
    fi

    if [ -n "${PULL_ALWAYS}" ]; then
        log_info "Pulling latest images (PULL_ALWAYS set)"
        run_compose pull
        return
    fi

    log_info "Pulling missing images only"

    _svc_img_pairs="$(
        run_compose config | awk '
            $1 == "services:" { in_services=1; next }
            in_services && match($0, /^[[:space:]]{2}[A-Za-z0-9_-]+:$/) {
                service=$1; sub(":", "", service); next
            }
            in_services && $1 == "image:" { print service, $2 }
        '
    )"

    _missing=""
    while IFS=" " read -r _svc _img; do
        [ -z "$_svc" ] || [ -z "$_img" ] && continue
        if docker image inspect "$_img" > /dev/null 2>&1; then
            log_info "Image present locally, skipping pull: $_svc ($_img)"
        else
            _missing="${_missing:+$_missing }$_svc"
        fi
    done << _PAIRS
$_svc_img_pairs
_PAIRS

    if [ -z "$_missing" ]; then
        log_success "All images present locally; skipping pull"
        return
    fi

    log_info "Pulling missing services: $_missing"
    # shellcheck disable=SC2086  (word-split intentional: service names)
    run_compose pull $_missing
}

clean_all() {
    log_warning "This will remove containers, networks, and unused images (including pulled ones)"
    printf "Are you sure? (y/N): "
    read -r REPLY
    case "$REPLY" in
        [Yy]*)
            log_info "Cleaning up..."
            run_compose down --rmi all --volumes --remove-orphans
            docker system prune -f
            log_success "Cleanup complete"
            ;;
        *)
            log_info "Cleanup cancelled"
            ;;
    esac
}

show_config() {
    log_info "Showing merged Docker Compose configuration"
    run_compose config
}

# =============================================================================
# SHELL FUNCTION INSTALLATION
#
# Detects the user's login shell and writes to the appropriate RC file(s).
# Supports bash (.bashrc), zsh (.zshrc), and generic POSIX (.profile).
# Also updates .bash_profile / .zprofile if they already exist (macOS).
# =============================================================================
install_shell_functions() {
    _isf_dir="${HOME}/.config/skewed-emacs"
    _isf_file="${_isf_dir}/shell-functions.sh"
    SHELL_HELPERS_CHANGED=false

    mkdir -p "${_isf_dir}"
    _isf_tmp="${_isf_dir}/shell-functions.sh.tmp.$$"

    # The snippet is pure POSIX sh -- works when sourced from any shell.
    cat > "${_isf_tmp}" << 'SNIPPET'
# Skewed Emacs shell helpers - auto-generated by compose-dev
# Works in bash, zsh, sh, or any POSIX-compatible shell.

# Both helpers are `docker exec` into the Captain's container.  A box may
# legitimately be running a hull with no Captain aboard -- a minimal
# roster, or a standalone Cyclops or KBE-server deployment -- and in that
# case docker's own "No such container: skewed-emacs" says nothing about
# what is actually going on.  Answer in the ship's own terms.
# Which Captain?  With more than one Basilisk on a box, container names
# carry the instance prefix, so reach another instance's Emacs with:
#     BASILISK_PREFIX=alpha- eskew
# Unset, this is exactly the historical "skewed-emacs".
_skew_captain() { printf '%s%s' "${BASILISK_PREFIX:-}" "${BASILISK_CAPTAIN:-captain}"; }

_skew_captain_aboard() {
    command -v docker >/dev/null 2>&1 || return 1
    [ "$(docker inspect -f '{{.State.Running}}' "$(_skew_captain)" 2>/dev/null)" = "true" ]
}

_skew_no_captain() {
    _snc_name="$(_skew_captain)"
    if ! command -v docker >/dev/null 2>&1; then
        printf '%s: docker not found on this host -- no way to reach the Captain.\n' "$1" >&2
    elif docker inspect "$_snc_name" >/dev/null 2>&1; then
        printf '%s: the Captain is aboard but not on watch (container "%s" is not running).\n' "$1" "$_snc_name" >&2
        printf '  Rouse the Captain:  docker start %s\n' "$_snc_name" >&2
    else
        printf '%s: no Captain aboard this ship (no "%s" container).\n' "$1" "$_snc_name" >&2
        printf '  Bring one aboard:  ./basilisk up\n' >&2
        printf '  Another instance?  BASILISK_PREFIX=<name>- %s\n' "$1" >&2
    fi
    return 1
}

eskew() {
    _skew_captain_aboard || { _skew_no_captain eskew; return 1; }
    docker exec -it --detach-keys "ctrl-^" "$(_skew_captain)" emacsclient -t "$@"
}

egskew() {
    _skew_captain_aboard || { _skew_no_captain egskew; return 1; }
    if [ -n "$DISPLAY" ] || [ -n "$WAYLAND_DISPLAY" ]; then
        docker exec -i -e DISPLAY="$DISPLAY" -e WAYLAND_DISPLAY="$WAYLAND_DISPLAY" \
            --detach-keys "ctrl-^" "$(_skew_captain)" emacsclient -c "$@" &
    else
        docker exec -it --detach-keys "ctrl-^" "$(_skew_captain)" emacsclient -t "$@"
    fi
}
SNIPPET

    if [ -f "${_isf_file}" ] && cmp -s "${_isf_tmp}" "${_isf_file}"; then
        rm -f "${_isf_tmp}"
        log_info "Shell functions already up to date in ${_isf_file}"
    else
        mv "${_isf_tmp}" "${_isf_file}"
        SHELL_HELPERS_CHANGED=true
        log_success "Shell functions written to ${_isf_file}"
    fi

    # Use '.' not 'source' -- POSIX portable
    _isf_source_line=". \"${_isf_file}\""

    # Primary RC based on login shell
    case "${SHELL##*/}" in
        zsh)  _isf_primary="${HOME}/.zshrc" ;;
        bash) _isf_primary="${HOME}/.bashrc" ;;
        ksh)  _isf_primary="${HOME}/.kshrc" ;;
        *)    _isf_primary="${HOME}/.profile" ;;
    esac

    # Belt and suspenders for fresh machines: login and non-login shells
    # read different RC files (.profile vs .bashrc), and a fresh account may
    # have SHELL=/bin/sh.  Ensure both .bashrc and .profile carry the source
    # line; the grep guard below keeps this idempotent.
    touch "$_isf_primary" "${HOME}/.bashrc" "${HOME}/.profile" 2>/dev/null || true

    _isf_wrote=false
    _isf_wrote_files=""
    # Write to primary, .bashrc, and .profile always; .bash_profile / .zprofile if they exist
    for _isf_rc in "$_isf_primary" "${HOME}/.bashrc" "${HOME}/.profile" \
                   "${HOME}/.bash_profile" "${HOME}/.zprofile"; do
        [ -f "$_isf_rc" ] || continue
        if grep -qF "skewed-emacs/shell-functions.sh" "$_isf_rc" 2>/dev/null; then
            log_info "Shell helpers already in ${_isf_rc} (no change needed)"
        else
            printf '\n# Skewed Emacs shell helpers\n%s\n' "$_isf_source_line" >> "$_isf_rc"
            log_success "Added skewed-emacs shell helpers to ${_isf_rc}"
            _isf_wrote=true
            _isf_wrote_files="${_isf_wrote_files:+${_isf_wrote_files}, }${_isf_rc}"
            SHELL_HELPERS_CHANGED=true
        fi
    done

    if [ "$_isf_wrote" = "true" ]; then
        log_info "Helpers wired into: ${_isf_wrote_files}"
        log_info "Open a new terminal (or run:  . ${_isf_file}  ) to activate eskew/egskew"
    fi
}

refresh_emacs_runtime_config() {
    _refresh_result="$(run_compose exec -T captain emacsclient --eval \
        "(progn
            (defvar skewed-runtime-services-refresh-armed nil)
            (defvar skewed-runtime-services-refresh-done nil)
            (defun skewed-runtime-services-refresh ()
              (when (and (require 'services-discovery nil t)
                         (not skewed-runtime-services-refresh-done))
                (setq skewed-runtime-services-refresh-done t)
                (skewed-reload-services)
                (when (and (require 'dashboard nil t)
                           (get-buffer \"*dashboard*\"))
                  (with-current-buffer \"*dashboard*\"
                    (dashboard-refresh-buffer)))
                'ok))
            (unless skewed-runtime-services-refresh-armed
              (setq skewed-runtime-services-refresh-armed t)
              (with-eval-after-load 'services-discovery
                (skewed-runtime-services-refresh))
              (with-eval-after-load 'dashboard
                (skewed-runtime-services-refresh)))
            (or (skewed-runtime-services-refresh) 'deferred))" 2>/dev/null || true)"

    case "$_refresh_result" in
        *ok*)
            log_success "Reloaded generated services in the running Emacs session"
            ;;
        *deferred*)
            log_info "Queued a final Emacs service refresh after startup completes"
            ;;
        "")
            log_info "Skipped immediate Emacs service refresh; the daemon is still initializing"
            ;;
        *)
            log_warning "Emacs service reload hook failed: ${_refresh_result}"
            ;;
    esac
}

show_skew_welcome() {
    echo ""
    echo "Services are Up.  The complement is aboard."
    echo ""
    echo "Shell Commands for the Basilisk Stack"
    echo ""
    printf "%b\n" "  \`eskew\`  ${BLUE}-- terminal emacsclient (attach in current terminal)${NC}"
    printf "%b\n" "  \`egskew\` ${BLUE}-- graphical emacsclient (opens new window)${NC}"
    echo ""
    echo "NOTE: Please exit this shell with Ctrl-D before doing './basilisk down'."
    echo "      (A down + up is a relief in place: same ship, all-new crew.)"
    echo ""
}

# =============================================================================
# MAIN
# =============================================================================
main() {
    # Variant switches: pick the skewed-emacs image variant for this
    # invocation (same names as docker/build targets).  They set
    # EMACS_IMAGE_VARIANT, which the compose image tag interpolates;
    # a shell-exported value wins over .env.  Works with any command
    # that touches images (up, pull, restart, config, ...).
    _remaining=""
    for _arg in "$@"; do
        case "$_arg" in
            --lite)              EMACS_IMAGE_VARIANT=lite ;;
            --default)           EMACS_IMAGE_VARIANT=default ;;
            --tui|--aituis)      EMACS_IMAGE_VARIANT=tui ;;
            --gui)               EMACS_IMAGE_VARIANT=gui ;;
            --full|--gui-aituis) EMACS_IMAGE_VARIANT=full ;;
            *) _remaining="${_remaining:+$_remaining
}$_arg" ;;
        esac
    done
    # No switch and nothing in the environment: fall back to this
    # clone's host pin, the same file systemd reads as an
    # EnvironmentFile.  Without this the two start paths disagree --
    # `systemctl start basilisk' honours the pin while `./basilisk up'
    # silently takes the compose default, which is `full', so a ship
    # pinned to `lite' flies heavy whenever anyone starts it by hand.
    if [ -f "$SCRIPT_DIR/systemd/host.env" ]; then
        # Every KEY=VALUE in host.env, not just the variant: it is this
        # clone's host pin file, and a production ingress pins its
        # published port there too.  Only fills values that are not
        # already set, so a flag or an inherited variable still wins.
        while IFS='=' read -r _k _v; do
            case "$_k" in ''|\#*) continue ;; esac
            if [ -z "$(eval "echo \${$_k:-}")" ]; then
                export "$_k=$_v"
            fi
        done < "$SCRIPT_DIR/systemd/host.env"
    fi
    if [ -n "${EMACS_IMAGE_VARIANT:-}" ]; then
        export EMACS_IMAGE_VARIANT
        log_info "skewed-emacs image variant: ${EMACS_IMAGE_VARIANT}"
    fi
    # Rebuild positional args minus the variant switches (newline
    # delimiter so service names with spaces would still be wrong, but
    # compose service names cannot contain spaces).
    if [ -n "$_remaining" ]; then
        _old_ifs=$IFS; IFS='
'
        # shellcheck disable=SC2086
        set -- $_remaining
        IFS=$_old_ifs
    else
        set --
    fi

    case "${1:-help}" in
        help|--help|-h) ;;
        *) preflight_checks || exit 1 ;;
    esac

    check_docker_compose

    case "${1:-help}" in
        up)
            shift
            _up_daemon=false
            _up_remaining=""
            for _up_arg in "$@"; do
                case "$_up_arg" in
                    --daemon|-d) _up_daemon=true ;;
                    --pull)      PULL_ALWAYS=1 ;;
                    *)           _up_remaining="${_up_remaining:+$_up_remaining }$_up_arg" ;;
                esac
            done
            # shellcheck disable=SC2086  (word-split intentional: service names)
            start_services $_up_remaining
            _up_rc=$?

            if [ "$_up_daemon" = "false" ]; then
                install_shell_functions
                if [ "$SHELL_HELPERS_CHANGED" = "true" ]; then
                    show_skew_welcome
                    exec "${SHELL:-sh}" -i
                fi
            fi
            # Propagate validation failure (systemd oneshot units watch
            # this exit status; the old code always exited 0 under -d).
            [ "$_up_rc" -eq 0 ] || exit "$_up_rc"
            ;;
        down)   stop_services ;;
        restart) shift; restart_services "$@" ;;
        stop)   shift; run_compose stop "$@" ;;
        logs)   shift; show_logs "$@" ;;
        status|ps) show_status ;;
        emacs)  connect_emacs ;;
        pull)   pull_images ;;
        clean)  clean_all ;;
        install-shell-functions) install_shell_functions ;;
        init)
            init_env
            ensure_env
            log_success "Environment initialized"
            ;;
        config) show_config ;;
        help|--help|-h) show_help ;;
        *)
            log_error "Unknown command: $1"
            printf "Use '%s help' for usage information\n" "$0"
            exit 1
            ;;
    esac
}

main "$@"