bobi 0.35.0__py3-none-any.whl

bobi/__main__.py

@@ -0,0 +1,3 @@
+from bobi.cli import main
+
+main()

bobi/__version__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("bobi")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

bobi/_deploy/Dockerfile

@@ -0,0 +1,263 @@
+# syntax=docker/dockerfile:1
+#
+# bobi instance image (containerized-8 / #338).
+#
+# ONE image, every tenant. Identity lives entirely in the mounted volume
+# (project root + $HOME) and env vars — see docs/design/CONTAINERIZED_INSTANCES.md
+# §2 (the instance contract). Nothing reaches in; the manager reaches out to the
+# event server over WSS only.
+#
+# ONE Dockerfile, three BUILD modes (BOBI_BUILD build-arg) — the runtime stage
+# is shared, so there's nothing to keep in sync:
+#   * source (default) — build the wheel from a repo checkout (`COPY . .`). Dev +
+#     the repo's own CI, so unreleased branch code is tested.
+#   * pypi             — install a published `bobi==$BOBI_VERSION` from
+#     PyPI; the build context is just this file + docker/. This is what binary-mode
+#     `bobi deploy` uses, so deploying needs no checkout (DEPLOY_INTERFACE.md).
+#   * wheel            — install a PREBUILT local wheel staged in dist/. The release
+#     pipeline (release.yml) builds the wheel once, then bakes THAT artifact so the
+#     canary smokes — and the fleet runs — the exact bytes published to PyPI.
+#
+# Design-mandated properties (CONTAINERIZED_INSTANCES.md §5, §6.1, §10 C8):
+#   * Runs the agent as a NON-ROOT user. Claude Code refuses bypassPermissions
+#     as root unless IS_SANDBOX=1; we drop privileges to `bobi` first.
+#   * No Node.js. The `claude` CLI is the native standalone binary (no npm).
+#   * fastembed model baked into the image at build (cold-start speed; immutable).
+#   * Pinned `claude` CLI; auto-updater disabled so the image version is frozen.
+#   * `bobi agent <name> start --foreground` as the entrypoint (C2); no tini — Fly's
+#     init is PID 1 (tini-on-Fly is a known boot-failure trigger).
+#
+# Build:
+#   docker build -t bobi:dev .                                  # source mode
+#   docker build --build-arg BOBI_BUILD=pypi \
+#     --build-arg BOBI_VERSION=0.22.0 -t bobi:dev .        # pypi mode
+#   docker build --build-arg BOBI_BUILD=wheel -t bobi:dev . # wheel (dist/*.whl)
+
+# Which builder produces /opt/venv: `source`, `pypi`, or `wheel`. bobi deploy
+# passes `pypi` (+ BOBI_VERSION) in binary mode; the release pipeline passes
+# `wheel` (with the prebuilt artifact in dist/); a plain `docker build` defaults to
+# `source` so the repo's own CI keeps building from the branch.
+ARG BOBI_BUILD=source
+
+#####################################################################
+# Builder base — build tools live here only; runtime never sees them.#
+#####################################################################
+FROM python:3.11-slim AS builder-base
+# apsw / native deps may need a compiler if no manylinux wheel is published.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+#####################################################################
+# builder-source — build the wheel FROM the repo (dev + repo CI).    #
+#####################################################################
+FROM builder-base AS builder-source
+RUN pip install --no-cache-dir build
+WORKDIR /src
+# --- deps layer (cached on pyproject only) -------------------------#
+# Install the project's runtime deps + the lean kb deps into the venv,
+# keyed on pyproject.toml alone: an ordinary code edit doesn't touch it, so
+# this (network-heavy) layer stays cached and only the thin wheel layer below
+# rebuilds. Read the dep list straight from [project.dependencies] (stdlib
+# tomllib) so it never drifts from pyproject. Install fastembed/sqlite-vec
+# EXPLICITLY — never the `[kb]` extra, which on some releases stale-lists
+# sentence-transformers → torch + ~2 GB CUDA the CPU instance never uses.
+COPY pyproject.toml ./
+RUN python -m venv /opt/venv \
+    && python -c "import tomllib; print(chr(10).join(tomllib.load(open('pyproject.toml','rb'))['project']['dependencies']))" > /tmp/reqs.txt \
+    && /opt/venv/bin/pip install --no-cache-dir -r /tmp/reqs.txt "fastembed>=0.4" "sqlite-vec>=0.1.6"
+# --- wheel layer (thin; rebuilds on any code change) ---------------#
+# pyproject builds the wheel FROM the sdist, so the sdist must carry the
+# force-included templates + event-server (it does — see pyproject sdist include).
+# --no-deps: deps are already in the venv above, so this is just bobi.
+COPY . .
+RUN python -m build --wheel --outdir /dist \
+    && /opt/venv/bin/pip install --no-cache-dir --no-deps /dist/*.whl
+
+#####################################################################
+# builder-pypi — install a published bobi (binary-mode deploy).#
+#####################################################################
+FROM builder-base AS builder-pypi
+# Pinned to the operator's CLI so the instance runs the same code as the binary
+# that deployed it.
+ARG BOBI_VERSION
+# Install the kb deps the code actually uses (fastembed — the lightweight ONNX
+# embedder — and sqlite-vec) EXPLICITLY, not via the `[kb]` extra: some published
+# releases stale-list `sentence-transformers` in `[kb]`, dragging in torch + ~2 GB
+# of CUDA wheels the dark CPU instance never uses (and that can blow the build
+# timeout). Keep in sync with pyproject's `[project.optional-dependencies].kb`.
+RUN python -m venv /opt/venv \
+    && /opt/venv/bin/pip install --no-cache-dir \
+        "bobi==${BOBI_VERSION}" "fastembed>=0.4" "sqlite-vec>=0.1.6"
+
+#####################################################################
+# builder-wheel — install a PREBUILT local wheel (release pipeline). #
+#####################################################################
+# The release pipeline builds the wheel ONCE in CI and stages it into the build
+# context at dist/ (re-included in .dockerignore). We install THAT exact artifact
+# here, so the canary smokes — and the fleet runs — the same bytes we publish to
+# PyPI (not a separately source-rebuilt wheel). Deps come from the same
+# pyproject-keyed layer as builder-source (cached across code-only changes); the
+# wheel goes in --no-deps on top.
+FROM builder-base AS builder-wheel
+WORKDIR /src
+COPY pyproject.toml ./
+RUN python -m venv /opt/venv \
+    && python -c "import tomllib; print(chr(10).join(tomllib.load(open('pyproject.toml','rb'))['project']['dependencies']))" > /tmp/reqs.txt \
+    && /opt/venv/bin/pip install --no-cache-dir -r /tmp/reqs.txt "fastembed>=0.4" "sqlite-vec>=0.1.6"
+# The prebuilt wheel staged by the release pipeline (exactly one *.whl in dist/).
+COPY dist/ /dist/
+RUN /opt/venv/bin/pip install --no-cache-dir --no-deps /dist/*.whl
+
+# Select the builder. With BOBI_BUILD=pypi, builder-source isn't in the graph
+# (its `COPY . .` never runs), so the tiny binary context needs no source tree.
+# BOBI_BUILD=wheel (the release pipeline) installs the prebuilt dist/ wheel.
+FROM builder-${BOBI_BUILD} AS builder
+
+#####################################################################
+# model-baker — pre-download the fastembed model. Keyed ONLY on the  #
+# pinned fastembed version, so this (the slowest layer — a multi-     #
+# minute model download) stays cached across every code/framework    #
+# change. Runtime COPYs the baked model in BELOW the volatile venv,   #
+# so a code-only rebuild never re-bakes it. (Install fastembed alone, #
+# never `[kb]` — see builder-source for the torch-bloat rationale.)   #
+#####################################################################
+FROM python:3.11-slim AS model-baker
+ENV HF_HOME=/opt/bobi/models
+RUN pip install --no-cache-dir "fastembed>=0.4" \
+    && python -c "from fastembed import TextEmbedding; TextEmbedding(model_name='sentence-transformers/all-MiniLM-L6-v2')" \
+    && chmod -R a+rX /opt/bobi/models
+
+#####################################################################
+# Runtime — slim image, no build tools, no Node. (Shared by both.)  #
+#####################################################################
+FROM python:3.11-slim AS runtime
+
+# Channel or exact version for the native `claude` installer. Default to the
+# `stable` channel (one week behind latest, skips major regressions); pass an
+# exact version (e.g. 2.1.89) for fully reproducible production builds.
+ARG CLAUDE_VERSION=stable
+ARG BOBI_UID=10001
+# Pinned aichat (the general-purpose LLM gateway CLI). Bump deliberately via
+# `gh api repos/sigoden/aichat/releases/latest --jq .tag_name`.
+ARG AICHAT_VERSION=0.30.0
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PATH="/opt/venv/bin:/home/bobi/.local/bin:${PATH}" \
+    HF_HOME=/opt/bobi/models \
+    DISABLE_AUTOUPDATER=1 \
+    HOME=/home/bobi \
+    DATA_DIR=/data \
+    BOBI_HOME=/data/.bobi
+# NB: HOME is the IMAGE home (above), NOT the volume — baked team tools
+# (~/.claude/skills, ~/dev/gstack) are read in place. Claude's durable state
+# (creds + transcripts) is redirected to the volume at runtime via
+# CLAUDE_CONFIG_DIR, which the entrypoint sets (NOT a build ENV — build steps
+# must write skills to the image ~/.claude, so they `env -u CLAUDE_CONFIG_DIR`).
+
+# Runtime packages only:
+#   curl, ca-certificates — fetch the claude installer; TLS
+#   gosu                  — drop privileges from root setup to the bobi user
+#   git                   — agents clone/operate on repos
+# NB: no tini. Fly Machines (the deploy target) inject their own PID-1 init that
+# reaps zombies + forwards signals, and layering tini on top is a documented
+# cause of "failed to spawn ... No such file or directory" boot failures there.
+# For other container runtimes, run with an init (e.g. `docker run --init`).
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        curl ca-certificates gosu git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Non-root runtime user (see header: bypassPermissions-as-root guard).
+RUN useradd --create-home --uid ${BOBI_UID} --shell /bin/bash bobi
+
+# Layers are ordered stable → volatile so a code-only rebuild touches only the
+# last (cheap) layers — the model download and `claude` fetch stay cached. See
+# docs/design/CUSTOM_AGENT_DEPS.md §"three clocks" for the ordering rationale.
+
+# --- stable layers (cached across code/framework changes) ----------#
+# Pinned native `claude` CLI (no Node) installed as the bobi user so it
+# lands in ~/.local/bin (on PATH above). Cache key is CLAUDE_VERSION alone.
+USER bobi
+RUN curl -fsSL https://claude.ai/install.sh | bash -s -- "${CLAUDE_VERSION}" \
+    && /home/bobi/.local/bin/claude --version
+USER root
+
+# General-purpose LLM gateway CLI (aichat): lets any agent call out to other
+# models over OpenAI-compatible endpoints — a one-shot model call, NOT agent
+# delegation (that's codex). Baked into the base image for every team, like
+# git/claude; the image stays generic — provider/model/key come from the team's
+# `gateway` connection + env at runtime, never from this layer. Pinned,
+# arch-detected static musl binary into /usr/local/bin (system-wide, on PATH).
+# Cache key is AICHAT_VERSION alone, so a code-only rebuild never re-fetches it.
+RUN arch="$(dpkg --print-architecture)" \
+    && case "$arch" in \
+         amd64) target=x86_64-unknown-linux-musl ;; \
+         arm64) target=aarch64-unknown-linux-musl ;; \
+         *) echo "aichat: unsupported arch $arch" >&2; exit 1 ;; \
+       esac \
+    && curl -fsSL "https://github.com/sigoden/aichat/releases/download/v${AICHAT_VERSION}/aichat-v${AICHAT_VERSION}-${target}.tar.gz" \
+       | tar -xz -C /usr/local/bin aichat \
+    && chmod +x /usr/local/bin/aichat \
+    && aichat --version
+
+# Baked fastembed embedding model (cold-start speed; immutable). HF_HOME points
+# here at both build and run, so it's a cache hit at runtime. Copied from
+# model-baker, whose only cache key is the fastembed version — so an ordinary
+# code change never re-downloads the model.
+COPY --from=model-baker /opt/bobi/models /opt/bobi/models
+
+# --- team-deps hook (C24 team-flavored images) ---------------------#
+# A team's baked host tools (node, codex, gstack, …) as ONE stable layer,
+# rendered from its `build:` spec by bobi/build_render.py and injected via
+# the TEAM_DEPS build-arg. The default is a no-op, so a plain build / a no-deps
+# team is byte-identical to the generic image. Positioned as the LAST stable
+# layer — just BELOW the volatile venv COPY — so a code-only framework release
+# rebuilds only the wheel, never re-runs the team's apt/npm/run. The hook runs
+# as root (USER is root here); it `gosu`s to bobi to bake ~-relative tools
+# into the image HOME (/home/bobi/.claude/skills, ~/dev/gstack), which the
+# agent reads in place at runtime — the entrypoint redirects only Claude's
+# durable state to the volume (CLAUDE_CONFIG_DIR) and symlinks skills back.
+# See docs/design/CUSTOM_AGENT_DEPS.md §"three clocks".
+ARG TEAM_DEPS=docker/noop-deps.sh
+COPY ${TEAM_DEPS} /tmp/team-deps.sh
+RUN bash /tmp/team-deps.sh && rm -f /tmp/team-deps.sh
+
+# --- volatile layer (rebuilds on any framework/code change) --------#
+# The prebuilt venv (bobi + deps) is the LAST heavy layer, so a code-only
+# rebuild is just this copy plus the thin layers below — seconds, not minutes.
+# Root-owned, world-readable.
+COPY --from=builder /opt/venv /opt/venv
+# Codex tool shells sanitize PATH and drop /opt/venv/bin. Surface the
+# framework CLI in both user-local and system bins so agents can call
+# `bobi` by bare name from Codex's current shell.
+RUN mkdir -p /home/bobi/.local/bin \
+    && printf '%s\n' '#!/bin/sh' 'exec /opt/venv/bin/bobi "$@"' \
+        > /usr/local/bin/bobi \
+    && cp /usr/local/bin/bobi /home/bobi/.local/bin/bobi \
+    && chown bobi:bobi /home/bobi/.local/bin/bobi \
+    && chmod +x /usr/local/bin/bobi /home/bobi/.local/bin/bobi
+
+COPY docker/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+COPY docker/healthcheck.sh /usr/local/bin/healthcheck.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh /usr/local/bin/healthcheck.sh
+
+# Persistent state lives on this volume. Bobi runtime state defaults to
+# /data/.bobi; Claude/Codex durable auth state uses /data/claude and /data/codex.
+VOLUME ["/data"]
+# WORKDIR must NOT be under /data: a volume mounted there shadows the
+# build-time dir, so the container's cwd ceases to exist at runtime and the
+# platform init (e.g. Fly Machines) fails to spawn the entrypoint with ENOENT.
+# The entrypoint binds BOBI_ROOT to the selected agent run directory.
+WORKDIR /
+
+# Liveness: read the manager's health port from the volume and probe /health.
+# start-period is generous — first boot installs a team and warms a session.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=180s --retries=3 \
+    CMD ["/usr/local/bin/healthcheck.sh"]
+
+# The entrypoint is PID 1 (under Fly's injected init): it does root-only volume
+# setup, then `exec gosu`s to the bobi user running the selected agent under
+# `bobi supervise`, so SIGTERM reaches the manager for graceful shutdown.
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]

bobi/_deploy/docker/docker-entrypoint.sh

@@ -0,0 +1,377 @@
+#!/usr/bin/env bash
+#
+# bobi container entrypoint (containerized-8 / #338).
+#
+# Runs as root (PID 1, under Fly's injected init — no tini; see Dockerfile) only
+# long enough to prepare the mounted volume, then drops to the non-root
+# `bobi` user and exec's the manager. Because the final step is
+# `exec gosu ... bobi supervise -- --foreground`, SIGTERM is forwarded to the
+# selected agent manager, which shuts sessions down gracefully (C2).
+#
+# First-boot install (empty volume -> `bobi agents install`) lives here for now so
+# the image is independently testable; #339 (C9) hardens the idempotency and
+# edge cases of this path.
+set -euo pipefail
+
+APP_USER="bobi"
+DATA_DIR="${DATA_DIR:-/data}"
+log() { echo "[entrypoint] $*"; }
+fatal() { echo "[entrypoint] FATAL: $*" >&2; exit 1; }
+# $HOME stays on the IMAGE (/home/bobi) — that's where baked team tools
+# (~/.claude/skills, ~/dev/gstack) live, read in place, never copied. Only
+# Claude's DURABLE state (credentials + transcripts + session history) is
+# redirected onto the volume via CLAUDE_CONFIG_DIR, the supported override.
+# Splitting the two this way (vs. seeding tools onto a volume HOME) keeps build
+# HOME == runtime HOME, so the image's `verify: requires` proves the live paths.
+export HOME="${HOME:-/home/bobi}"
+[ -n "${BOBI_HOME:-}" ] || fatal "BOBI_HOME is required. The image sets BOBI_HOME=/data/.bobi."
+export BOBI_HOME
+export CLAUDE_CONFIG_DIR="${CLAUDE_CONFIG_DIR:-${DATA_DIR}/claude}"
+
+if [ -n "${BOBI_AGENT:-}" ]; then
+  AGENT_NAME="${BOBI_AGENT}"
+elif [ -n "${BOBI_INSTANCE:-}" ]; then
+  AGENT_NAME="${BOBI_INSTANCE}"
+elif [ -n "${BOBI_ROOT:-}" ] && [ "$(basename "${BOBI_ROOT}")" = "run" ]; then
+  AGENT_NAME="$(basename "$(dirname "${BOBI_ROOT}")")"
+else
+  fatal "No Bobi Agent selected. Set BOBI_INSTANCE, BOBI_AGENT, or BOBI_ROOT."
+fi
+RUN_ROOT="${BOBI_ROOT:-${BOBI_HOME}/agents/${AGENT_NAME}/run}"
+export BOBI_ROOT="${RUN_ROOT}"
+PACKAGE_DIR="${RUN_ROOT}/package"
+
+# The agent brain (#485). Decides the provider API key (api_key/subscription),
+# the durable OAuth credential dir on the volume, and the credential file the
+# first-boot subscription bootstrap waits for. Default claude for entrypoint
+# branching only; do not export that default because agent.yaml must still be
+# able to select a non-Claude brain when BOBI_BRAIN was not explicit.
+ENTRYPOINT_BRAIN="${BOBI_BRAIN:-claude}"
+
+configure_brain_paths() {
+  case "$ENTRYPOINT_BRAIN" in
+    codex)
+      BRAIN_SHADOW_KEY="OPENAI_API_KEY"
+      BRAIN_CRED_DIR="${DATA_DIR}/codex"      # ~/.codex symlinks here
+      BRAIN_HOME_LINK="${HOME}/.codex"
+      BRAIN_CRED_FILE="auth.json"
+      ;;
+    *)  # claude (default): durable state already lives under CLAUDE_CONFIG_DIR
+      BRAIN_SHADOW_KEY="ANTHROPIC_API_KEY"
+      BRAIN_CRED_DIR="${CLAUDE_CONFIG_DIR}"
+      BRAIN_HOME_LINK="${HOME}/.claude"
+      BRAIN_CRED_FILE=".credentials.json"
+      ;;
+  esac
+}
+
+validate_auth_mode() {
+  # The provider API key is brain-specific (ANTHROPIC_API_KEY / OPENAI_API_KEY);
+  # ${!BRAIN_SHADOW_KEY} is its live value via bash indirect expansion.
+  case "${BOBI_AUTH:-api_key}" in
+    api_key)
+      [ -n "${!BRAIN_SHADOW_KEY:-}" ] \
+        || fatal "BOBI_AUTH=api_key but ${BRAIN_SHADOW_KEY} is unset."
+      ;;
+    subscription)
+      # The provider API key silently outranks subscription OAuth creds and bills
+      # the API instead — it must be entirely absent in this mode (§6.1).
+      [ -z "${!BRAIN_SHADOW_KEY:-}" ] \
+        || fatal "BOBI_AUTH=subscription but ${BRAIN_SHADOW_KEY} is set; it overrides subscription auth. Unset it."
+      ;;
+    *)
+      fatal "unknown BOBI_AUTH='${BOBI_AUTH}' (expected api_key|subscription)."
+      ;;
+  esac
+}
+
+resolve_configured_brain() {
+  [ -z "${BOBI_BRAIN:-}" ] || return 0
+  [ -f "${PACKAGE_DIR}/agent.yaml" ] || return 0
+
+  local configured
+  if configured="$(BOBI_ROOT="${RUN_ROOT}" python - <<'PY' 2>/dev/null
+import os
+from pathlib import Path
+
+from bobi.config import Config
+
+print(Config.load(Path(os.environ["BOBI_ROOT"])).brain_kind or "", end="")
+PY
+  )" && [ -n "${configured}" ]; then
+    ENTRYPOINT_BRAIN="${configured}"
+  fi
+}
+
+resolve_configured_brain
+configure_brain_paths
+
+materialize_codex_api_key_auth() {
+  local cred_dir="$1"
+  [ -n "${OPENAI_API_KEY:-}" ] || return 0
+  log "Writing Codex API-key auth file from OPENAI_API_KEY"
+  mkdir -p "${cred_dir}"
+  CODEX_CRED_DIR="${cred_dir}" OPENAI_API_KEY="${OPENAI_API_KEY}" python - <<'PY'
+import json
+import os
+from pathlib import Path
+
+path = Path(os.environ["CODEX_CRED_DIR"]) / "auth.json"
+path.write_text(json.dumps({"OPENAI_API_KEY": os.environ["OPENAI_API_KEY"]}) + "\n")
+path.chmod(0o600)
+PY
+  chown -R "${APP_USER}:${APP_USER}" "${cred_dir}"
+}
+
+codex_auth_uses_api_key() {
+  local cred_dir="$1"
+  CODEX_CRED_DIR="${cred_dir}" python - <<'PY'
+import json
+import os
+import sys
+from pathlib import Path
+
+try:
+    data = json.loads((Path(os.environ["CODEX_CRED_DIR"]) / "auth.json").read_text())
+except Exception:
+    sys.exit(1)
+sys.exit(0 if isinstance(data, dict) and "OPENAI_API_KEY" in data else 1)
+PY
+}
+
+AUTH_VALIDATED=0
+if [ -n "${BOBI_BRAIN:-}" ] \
+   || [ -f "${PACKAGE_DIR}/agent.yaml" ] \
+   || { [ -z "${BOBI_TEAM_URL:-}" ] && [ -z "${BOBI_TEAM:-}" ]; }; then
+  validate_auth_mode
+  AUTH_VALIDATED=1
+fi
+
+# --- 1. Prepare the volume (root) -------------------------------------------
+# Only durable state lives on the volume: BOBI_HOME, the selected run root, and
+# Claude's config dir (CLAUDE_CONFIG_DIR). HOME is on the image and needs no
+# volume prep.
+mkdir -p "${BOBI_HOME}" "${RUN_ROOT}" "${RUN_ROOT}/workspace" "${CLAUDE_CONFIG_DIR}"
+
+# Fly/EC2/k8s mount fresh volumes owned by root. Take ownership once so the
+# non-root user can write; a stamp keeps subsequent boots from re-walking a
+# large, already-correct tree.
+if [ ! -e "${DATA_DIR}/.bobi-owned" ]; then
+  log "Taking ownership of ${DATA_DIR} for ${APP_USER} (first boot)"
+  chown -R "${APP_USER}:${APP_USER}" "${DATA_DIR}"
+  : > "${DATA_DIR}/.bobi-owned"
+else
+  chown "${APP_USER}:${APP_USER}" "${DATA_DIR}" "${BOBI_HOME}" "${RUN_ROOT}" "${CLAUDE_CONFIG_DIR}"
+fi
+
+# --- 1b. Make ~/.claude coincide with the durable volume config dir (C24) -----
+# $HOME stays on the image (baked tools read in place), but Claude's DURABLE
+# state (creds, transcripts, settings) lives under CLAUDE_CONFIG_DIR on the
+# volume. Point the whole ~/.claude AT that dir, so any tool/skill that hardcodes
+# ~/.claude/{projects,settings.json,skills,…} sees Claude's real state — one
+# coherent home tree, split underneath only by storage lifecycle (image vs
+# volume), invisible to anything using `~`.
+#
+# Personal skills are baked OUTSIDE ~/.claude at /opt/bobi/skills (immutable
+# image content; build-render.py put them there) and surfaced via the config
+# dir's skills/ entry — a symlinked DIRECTORY is safe (files read inside it) and
+# resolves to the exact path the build's `verify: requires` checked. No baked
+# skills (generic image) → that link is skipped; Claude finds project skills.
+if [ -d /opt/bobi/skills ]; then
+  log "Linking ${CLAUDE_CONFIG_DIR}/skills -> /opt/bobi/skills (baked team skills)"
+  ln -sfn /opt/bobi/skills "${CLAUDE_CONFIG_DIR}/skills"
+fi
+# Replace the image's real ~/.claude (created at build) with a symlink to the
+# volume config dir. Idempotent: rewrite only when it isn't already that link
+# (a fresh image rootfs each deploy ships the real dir; a same-machine restart
+# already has the link). rm -rf only ever discards ephemeral image content —
+# the durable state and the baked skills both live elsewhere.
+if [ "$(readlink "${HOME}/.claude" 2>/dev/null)" != "${CLAUDE_CONFIG_DIR}" ]; then
+  log "Pointing ${HOME}/.claude -> ${CLAUDE_CONFIG_DIR} (durable config on volume)"
+  rm -rf "${HOME}/.claude"
+  ln -s "${CLAUDE_CONFIG_DIR}" "${HOME}/.claude"
+fi
+
+cd "${RUN_ROOT}"
+
+# Carry HOME (the image home), BOBI_HOME/BOBI_ROOT (the durable selected Bobi
+# runtime), and CLAUDE_CONFIG_DIR (the volume dir holding durable
+# creds/transcripts) into every privilege drop.
+as_app() {
+  if [ -n "${BOBI_BRAIN:-}" ] || [ "${ENTRYPOINT_BRAIN}" != "claude" ]; then
+    gosu "${APP_USER}" env "HOME=${HOME}" "BOBI_HOME=${BOBI_HOME}" "BOBI_ROOT=${BOBI_ROOT}" "CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}" "BOBI_BRAIN=${ENTRYPOINT_BRAIN}" "$@"
+  else
+    gosu "${APP_USER}" env "HOME=${HOME}" "BOBI_HOME=${BOBI_HOME}" "BOBI_ROOT=${BOBI_ROOT}" "CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}" "$@"
+  fi
+}
+
+# --- 2. First boot: install a team if the volume has no agent (C9 hardens) ---
+# Team source precedence: a public BOBI_TEAM_URL (fetched at boot — the
+# dark instance reaches out, nothing reaches in) wins over BOBI_TEAM (a
+# bundled/registry name).
+#
+# With NEITHER set on an empty volume the instance enters the "wait for team"
+# state instead of crashing: it was provisioned blank for ssh-push delivery
+# (`bobi deploy` with a local `team:` package — DEPLOY_INTERFACE.md). The
+# operator pushes the team over `fly ssh` (sftp the tarball + `bobi agents install`),
+# which lands run/package/agent.yaml on the volume; we poll for it, then start.
+# This is the single-developer "I built it, ship it — no hosting" path, and it
+# keeps PID 1 alive so the Fly machine stays "started" while we wait.
+if [ ! -f "${PACKAGE_DIR}/agent.yaml" ]; then
+  if [ -n "${BOBI_TEAM_URL:-}" ]; then
+    log "First boot: installing team from URL ${BOBI_TEAM_URL} (non-interactive)"
+    as_app bobi agents install "${BOBI_TEAM_URL}" --name "${AGENT_NAME}" --non-interactive
+  elif [ -n "${BOBI_TEAM:-}" ]; then
+    log "First boot: installing team '${BOBI_TEAM}' (non-interactive)"
+    # BOBI_TEAM must resolve to something the INSTANCE can see: a path on the
+    # volume (e.g. an ssh-pushed /mnt/team) or a local package — there is NO team
+    # registry baked into the image, so a bare name won't resolve. Fail LOUD with
+    # the actionable alternative instead of letting `set -e` crash-loop the Fly
+    # machine on a bare pipefail trace (C9/#339).
+    if ! as_app bobi agents install "${BOBI_TEAM}" --name "${AGENT_NAME}" --non-interactive; then
+      log "ERROR: couldn't install team '${BOBI_TEAM}'. The container has no"
+      log "       team registry, so BOBI_TEAM only resolves a path/package the"
+      log "       instance can already see. To deliver a PUBLISHED team, set"
+      log "       BOBI_TEAM_URL=<https .tar.gz> instead; to deliver a LOCAL"
+      log "       package, use 'bobi deploy <name>' (ssh-push, no team source"
+      log "       on the instance). See DEPLOYMENT.md / DEPLOY_INTERFACE.md."
+      exit 1
+    fi
+  else
+    log "No team source and empty volume — blank instance, waiting for an"
+    log "ssh-push team delivery (bobi deploy). Poll for ${PACKAGE_DIR}/agent.yaml..."
+    waited=0
+    while [ ! -f "${PACKAGE_DIR}/agent.yaml" ]; do
+      sleep 2
+      waited=$((waited + 2))
+      # Heartbeat every ~2 min so `fly logs` shows the instance is alive, not hung.
+      if [ $((waited % 120)) -eq 0 ]; then
+        log "Still waiting for a pushed team (${waited}s)..."
+      fi
+    done
+    log "Team appeared on the volume after ${waited}s — proceeding to start."
+  fi
+fi
+
+resolve_configured_brain
+configure_brain_paths
+
+# --- 3. Validate auth mode --------------------------------------------------
+# First-boot team installs can define ``brain.kind`` in agent.yaml, so their
+# shadow-key check may need to wait until after install. Blank/no-team boots and
+# existing installs validate before the wait-for-team loop so auth mistakes fail
+# fast instead of hanging as a blank instance.
+if [ "${AUTH_VALIDATED}" != "1" ]; then
+  validate_auth_mode
+fi
+
+# --- 3b. Codex's durable OAuth dir on the volume (#485) ---------------------
+# Same idea for codex: ~/.codex (where `codex login`/`codex exec` keep auth.json)
+# points at a volume dir so the ChatGPT subscription survives a redeploy. claude
+# already gets this via CLAUDE_CONFIG_DIR above; codex has no config-dir override,
+# so we symlink the home dir directly.
+if [ "${ENTRYPOINT_BRAIN}" = "codex" ]; then
+  mkdir -p "${BRAIN_CRED_DIR}"
+  chown "${APP_USER}:${APP_USER}" "${BRAIN_CRED_DIR}"
+  if [ -d /opt/bobi/skills ]; then
+    log "Linking baked team skills into ${BRAIN_CRED_DIR}/skills for codex"
+    mkdir -p "${BRAIN_CRED_DIR}/skills"
+    chown "${APP_USER}:${APP_USER}" "${BRAIN_CRED_DIR}/skills"
+    for existing_skill in "${BRAIN_CRED_DIR}/skills"/*; do
+      [ -L "${existing_skill}" ] || continue
+      existing_target="$(readlink "${existing_skill}")"
+      case "${existing_target}" in
+        /opt/bobi/skills/*)
+          if [ ! -e "${existing_target}" ]; then
+            log "Removing stale baked codex skill link ${existing_skill}"
+            rm -f "${existing_skill}"
+          fi
+          ;;
+      esac
+    done
+    for skill_path in /opt/bobi/skills/*; do
+      [ -e "${skill_path}" ] || continue
+      skill_name="$(basename "${skill_path}")"
+      skill_dest="${BRAIN_CRED_DIR}/skills/${skill_name}"
+      if [ -e "${skill_dest}" ] || [ -L "${skill_dest}" ]; then
+        if [ -L "${skill_dest}" ]; then
+          skill_dest_target="$(readlink "${skill_dest}")"
+          case "${skill_dest_target}" in
+            /opt/bobi/skills/*) ;;
+            *)
+              log "Leaving existing codex skill link at ${skill_dest}; baked skill ${skill_name} not linked"
+              continue
+              ;;
+          esac
+        else
+          log "Leaving existing codex skill at ${skill_dest}; baked skill ${skill_name} not linked"
+          continue
+        fi
+      fi
+      ln -sfnT "${skill_path}" "${skill_dest}"
+    done
+  fi
+  if [ "$(readlink "${BRAIN_HOME_LINK}" 2>/dev/null)" != "${BRAIN_CRED_DIR}" ]; then
+    log "Pointing ${BRAIN_HOME_LINK} -> ${BRAIN_CRED_DIR} (durable codex creds on volume)"
+    rm -rf "${BRAIN_HOME_LINK}"
+    ln -s "${BRAIN_CRED_DIR}" "${BRAIN_HOME_LINK}"
+  fi
+fi
+
+# The Codex CLI also exists as an auxiliary tool for Claude-brained teams
+# (`tool_library: [codex]`). Unlike Claude, Codex does not read OPENAI_API_KEY
+# directly; it expects ~/.codex/auth.json. In subscription mode, never turn an
+# ambient API key into Codex auth: subscription OAuth must remain authoritative.
+if [ "${BOBI_AUTH:-api_key}" != "subscription" ]; then
+  if [ "${ENTRYPOINT_BRAIN}" = "codex" ]; then
+    materialize_codex_api_key_auth "${BRAIN_CRED_DIR}"
+  else
+    materialize_codex_api_key_auth "${HOME}/.codex"
+  fi
+elif [ -n "${OPENAI_API_KEY:-}" ]; then
+  log "Subscription mode: leaving OPENAI_API_KEY out of Codex auth materialization"
+fi
+
+if [ "${BOBI_AUTH:-api_key}" = "subscription" ]; then
+  if [ "${ENTRYPOINT_BRAIN}" = "codex" ]; then
+    codex_dir="${BRAIN_CRED_DIR}"
+  else
+    codex_dir="${HOME}/.codex"
+  fi
+  if codex_auth_uses_api_key "${codex_dir}"; then
+    log "Subscription mode: removing Codex API-key auth file so OAuth can be used"
+    rm -f "${codex_dir}/auth.json"
+  fi
+fi
+
+# --- 4. Subscription auth: bootstrap login over Slack if no creds yet (C23) --
+# Idempotent: a no-op once the credentials exist. They live under
+# CLAUDE_CONFIG_DIR (the volume), not HOME — that's the durable state we keep.
+if [ "${BOBI_AUTH:-api_key}" = "subscription" ] \
+   && [ ! -f "${BRAIN_CRED_DIR}/${BRAIN_CRED_FILE}" ]; then
+  log "Subscription mode, no ${ENTRYPOINT_BRAIN} credentials on volume — running login bootstrap"
+  as_app bobi agent "${AGENT_NAME}" login-bootstrap
+fi
+
+# --- 5. Hand off to the manager as the non-root user ------------------------
+# Agent UI on by default IN THE CONTAINER (the manager starts it on the private
+# 6PN; reach it with `bobi agent <name> ui <deployment>` / `fly proxy`). It's image
+# behavior, not a per-instance flag, so existing instances pick it up on their
+# next image swap. Disable with BOBI_UI=0 in the Fly env. The dark instance
+# has no public route, so this exposes nothing — see DESIGN.md "Agent UI".
+export BOBI_UI="${BOBI_UI:-1}"
+log "Starting manager under self-heal watchdog (user=${APP_USER}, agent=${AGENT_NAME}, run=${RUN_ROOT}, home=${HOME}, bobi_home=${BOBI_HOME}, claude_config=${CLAUDE_CONFIG_DIR})"
+# #464: launch the manager under `bobi supervise` instead of directly.
+# The supervisor is the entrypoint process (parent); it spawns the manager as a
+# child, watches the director's progress via the health endpoint, and restarts
+# a wedged director from below — the one recovery layer stall-recovery cannot
+# provide. It runs no agent loop, so it cannot wedge from the same cause; on
+# restart-budget exhaustion it exits non-zero and Fly's machine restart policy
+# escalates. `healthcheck.sh` is unaffected (the manager child still writes the
+# port file). The forwarded `--foreground` keeps the manager a supervisable
+# child rather than letting it daemonize.
+if [ -n "${BOBI_BRAIN:-}" ] || [ "${ENTRYPOINT_BRAIN}" != "claude" ]; then
+  exec gosu "${APP_USER}" env "HOME=${HOME}" "BOBI_HOME=${BOBI_HOME}" "BOBI_ROOT=${BOBI_ROOT}" "CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}" "BOBI_BRAIN=${ENTRYPOINT_BRAIN}" "BOBI_UI=${BOBI_UI}" bobi supervise -- --foreground "$@"
+else
+  exec gosu "${APP_USER}" env "HOME=${HOME}" "BOBI_HOME=${BOBI_HOME}" "BOBI_ROOT=${BOBI_ROOT}" "CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}" "BOBI_UI=${BOBI_UI}" bobi supervise -- --foreground "$@"
+fi