fix: drive build from lpb.stack.env/lpb.conf.env, harden launcher + tests

lpb.py regressions from recent refactors (all now covered by tests):
  - cmd_remove called .is_dir() on the str from resolve_path() -> AttributeError
  - _load_stack_env/_load_conf_env only looked next to the script, silently
    ignoring lpb.stack.env/lpb.conf.env when run from a checkout
  - separator comment swallowed `def self_update()`, so cmd_update would
    NameError at runtime (body was absorbed into warn())

Canonical config now drives the build:
  - support/build.sh sources lpb.stack.env + lpb.conf.env and passes
    --build-arg for every value (CONFIG_FORK, CONFIG_REF, NODE_VERSION,
    VSCODIUM_VERSION, PI_*, LPB_VERSION, LPB_MAX_TOKENS_CONTEXT_RATIO, ...)
  - Dockerfile: new ARGs/ENVs, bakes CONFIG_FORK/REF as LPB_CONFIG_REMOTE/REF
    and copies lpb.stack.env into /opt/devstack/
  - CI cli/web jobs pass PI_REF, PI_HEAD_SHA, LPB_VERSION and MAX_TOKENS and
    apply them on push

Tests (scripts/test_lpb.py): 15 -> 27, incl. structural guards for swallowed
defs, env-file discovery, host-path semantics, remove confirm/abort, update
path, and web-mode env/volume assertions; mutation tests prove the guards
catch the two historic regressions. CI runs the suite and gates image builds.

Docs: fix stale /home/dev -> /home/lpb; add doc/LAUNCHER-INTERNALS.md.

Author: localpibox

.github/workflows/build-and-publish.yml

@@ -30,6 +30,7 @@ on:
       - 'lpb.stack.env'
       - 'lpb.conf.env'
       - '.github/workflows/*.yml'
+      - 'scripts/**'
   pull_request:
     branches: [main]
     paths:
@@ -38,6 +39,7 @@ on:
       - 'lpb.stack.env'
       - 'lpb.conf.env'
       - '.github/workflows/*.yml'
+      - 'scripts/**'
   schedule:
     - cron: '0 3 * * 1'
   workflow_dispatch:
@@ -59,10 +61,21 @@ env:
   IMAGE_NAME: ghcr.io/localpibox/devstack
 
 jobs:
+  test-lpb:
+    name: Run lpb.py unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Run test suite
+        run: python3 scripts/test_lpb.py
+
   build-cli:
     name: Build & publish cli image
     runs-on: ubuntu-latest
     timeout-minutes: 45
+    needs: [test-lpb]
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -92,6 +105,9 @@ jobs:
           echo "CONFIG_REF=$LPB_CONFIG_REF" >> "$GITHUB_OUTPUT"
           echo "NODE_VERSION=$LPB_NODE_VERSION" >> "$GITHUB_OUTPUT"
           echo "VSCODIUM_VERSION=$LPB_VSCODIUM_VERSION" >> "$GITHUB_OUTPUT"
+          echo "LPB_VERSION=$(cat VERSION 2>/dev/null || echo unknown)" >> "$GITHUB_OUTPUT"
+          MAX_TOKENS=$(grep -E '^LPB_MAX_TOKENS_CONTEXT_RATIO=' lpb.conf.env | cut -d= -f2- | tr -d '"' 2>/dev/null || true)
+          echo "MAX_TOKENS=${MAX_TOKENS:-0.06}" >> "$GITHUB_OUTPUT"
           sha=$(git ls-remote "$LPB_PI_FORK" "refs/heads/$LPB_PI_REF" | awk '{print $1}')
           # Read stack version from config repo
           cfg_repo=$(echo "$LPB_CONFIG_FORK" | sed -E 's#https://github.com/([^/]+)/([^./]+)\.git#\1/\2#')
@@ -116,6 +132,8 @@ jobs:
             NODE_VERSION=${{ steps.config.outputs.NODE_VERSION }}
             VSCODIUM_VERSION=${{ steps.config.outputs.VSCODIUM_VERSION }}
             PI_HEAD_SHA=${{ steps.config.outputs.sha }}
+            LPB_VERSION=${{ steps.config.outputs.LPB_VERSION }}
+            LPB_MAX_TOKENS_CONTEXT_RATIO=${{ steps.config.outputs.MAX_TOKENS }}
           no-cache: ${{ github.event.inputs.no_cache == 'true' }}
           tags: |
             ${{ env.IMAGE_NAME }}:cli
@@ -162,6 +180,9 @@ jobs:
           echo "CONFIG_REF=$LPB_CONFIG_REF" >> "$GITHUB_OUTPUT"
           echo "NODE_VERSION=$LPB_NODE_VERSION" >> "$GITHUB_OUTPUT"
           echo "VSCODIUM_VERSION=$LPB_VSCODIUM_VERSION" >> "$GITHUB_OUTPUT"
+          echo "LPB_VERSION=$(cat VERSION 2>/dev/null || echo unknown)" >> "$GITHUB_OUTPUT"
+          MAX_TOKENS=$(grep -E '^LPB_MAX_TOKENS_CONTEXT_RATIO=' lpb.conf.env | cut -d= -f2- | tr -d '"' 2>/dev/null || true)
+          echo "MAX_TOKENS=${MAX_TOKENS:-0.06}" >> "$GITHUB_OUTPUT"
           sha=$(git ls-remote "$LPB_PI_FORK" "refs/heads/$LPB_PI_REF" | awk '{print $1}')
           # Read stack version from config repo
           cfg_repo=$(echo "$LPB_CONFIG_FORK" | sed -E 's#https://github.com/([^/]+)/([^./]+)\.git#\1/\2#')
@@ -180,11 +201,14 @@ jobs:
           cache-to: type=gha,mode=max
           build-args: |
             PI_FORK=${{ steps.config.outputs.PI_FORK }}
+            PI_REF=${{ steps.config.outputs.PI_REF }}
             CONFIG_FORK=${{ steps.config.outputs.CONFIG_FORK }}
             CONFIG_REF=${{ steps.config.outputs.CONFIG_REF }}
             NODE_VERSION=${{ steps.config.outputs.NODE_VERSION }}
             VSCODIUM_VERSION=${{ steps.config.outputs.VSCODIUM_VERSION }}
             PI_HEAD_SHA=${{ steps.config.outputs.sha }}
+            LPB_VERSION=${{ steps.config.outputs.LPB_VERSION }}
+            LPB_MAX_TOKENS_CONTEXT_RATIO=${{ steps.config.outputs.MAX_TOKENS }}
           no-cache: ${{ github.event.inputs.no_cache == 'true' }}
           tags: |
             ${{ env.IMAGE_NAME }}:web

Dockerfile

@@ -21,15 +21,25 @@
 # ═══════════════════════════════════════════════════════════════════════════
 
 # Source fork configuration — ARG defaults come from lpb.stack.env
+# Instead of editing this file, edit lpb.stack.env (canonical) and either:
+#   - run support/build.sh (reads lpb.stack.env + lpb.conf.env), or
+#   - pass --build-arg per value.
 # NOTE: Docker ARG values can't reference source'd shell variables.
-# The ARGs below are the definitive defaults. CI sets them via
-#   docker build --build-arg PI_FORK=... etc.
 ARG NODE_VERSION=24
 ARG VSCODIUM_VERSION=1.126.04524
 ARG PI_FORK=https://github.com/localpibox/pi.git
 ARG PI_REF=lpb
 ARG PI_HEAD_SHA=unknown
 
+# Config preset repo — baked so start.sh clones the fork's config at boot.
+# (CI passes these from lpb.stack.env LPB_CONFIG_FORK / LPB_CONFIG_REF.)
+ARG CONFIG_FORK=https://github.com/localpibox/config.git
+ARG CONFIG_REF=main
+
+# Runtime defaults baked from lpb.conf.env (start.sh can still override).
+ARG LPB_MAX_TOKENS_CONTEXT_RATIO=0.06
+ARG LPB_VERSION=unknown
+
 # Provenance — set via --build-arg in CI, defaults to "unknown" for local builds
 ARG IMAGE_REVISION=unknown
 ARG IMAGE_BUILT=unknown
@@ -44,16 +54,23 @@ ARG VSCODIUM_VERSION
 ARG PI_FORK
 ARG PI_REF
 ARG PI_HEAD_SHA
+ARG CONFIG_FORK
+ARG CONFIG_REF
+ARG LPB_MAX_TOKENS_CONTEXT_RATIO
+ARG LPB_VERSION
 ARG IMAGE_REVISION
 ARG IMAGE_BUILT
 
 ENV DEBIAN_FRONTEND=noninteractive
 
-# Context window / max tokens ratio — baked into image.
-# 0.06 (6%) — reduced from 0.125 for Qwen thinking models.
+# Context window / max tokens ratio — baked into image from lpb.conf.env.
 # Container-level overrides take precedence via --env or -e at runtime.
-ENV LPB_MAX_TOKENS_CONTEXT_RATIO=0.06
-ENV LPB_VERSION=
+ENV LPB_MAX_TOKENS_CONTEXT_RATIO=${LPB_MAX_TOKENS_CONTEXT_RATIO}
+# Stack/version banner value (baked from lpb.conf.env).
+ENV LPB_VERSION=${LPB_VERSION}
+# Baked from lpb.stack.env/CI — start.sh reads these for the config repo clone.
+ENV LPB_CONFIG_REMOTE=${CONFIG_FORK}
+ENV LPB_CONFIG_REF=${CONFIG_REF}
 
 # ── System packages ─────────────────────────────────────────────────────────
 RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -158,6 +175,7 @@ COPY --chmod=755 support/validate.sh /opt/devstack/validate.sh
 COPY --chmod=755 support/install-openspec.sh /opt/pi-support/install-openspec.sh
 COPY --chmod=755 support/start.sh /opt/devstack/start.sh
 COPY lpb.conf.env /opt/devstack/lpb.conf.env
+COPY lpb.stack.env /opt/devstack/lpb.stack.env
 COPY --chmod=755 support/entrypoint-cli.sh /opt/devstack/entrypoint-cli.sh
 
 # ── Shell PATH helper ───────────────────────────────────────────────────────

QUICK-START.md

@@ -51,12 +51,12 @@ podman run -d \
     --userns keep-id \
     -e LPB_ED_PORT=3000 \
     -e LPB_EDITOR_HOST=0.0.0.0 \
-    -e LPB_DEVCONTAINER_WORKSPACE_DIR="/home/dev/workspace/$PROJECT_NAME" \
+    -e LPB_DEVCONTAINER_WORKSPACE_DIR="/home/lpb/workspace/$PROJECT_NAME" \
     -e LPB_CONNECTION_TOKEN=devsession \
     -e LPB_EXA_API_KEY=your-exa-key \
-    -v "$PROJECT_DIR:/home/dev/workspace/$PROJECT_NAME:Z" \
-    -v "$STATE_DIR:/home/dev/.pi:Z" \
-    -v "$BROWSER_DIR:/home/dev/.agent-browser:Z" \
+    -v "$PROJECT_DIR:/home/lpb/workspace/$PROJECT_NAME:Z" \
+    -v "$STATE_DIR:/home/lpb/.pi:Z" \
+    -v "$BROWSER_DIR:/home/lpb/.agent-browser:Z" \
     ghcr.io/localpibox/devstack:latest
 ```
 
@@ -93,8 +93,8 @@ xdg-open http://localhost:3000
 ## Architecture
 
 ```
-Host:  ~/projects/myproject/    → Container: /home/dev/workspace/myproject/
-Host:  ~/.localpibox/state/     → Container: /home/dev/.pi/
+Host:  ~/projects/myproject/    → Container: /home/lpb/workspace/myproject/
+Host:  ~/.localpibox/state/     → Container: /home/lpb/.pi/
 Host:  (Lemonade on host)       → Container: http://127.0.0.1:13305 (via --network host)
 ```
 

README.md

@@ -32,9 +32,9 @@ podman pull ghcr.io/localpibox/devstack:latest
 
 # Run with a project folder
 podman run -d --name localpibox --network host --userns keep-id \
-    -v /path/to/your/project:/home/dev/workspace/myproject:Z \
-    -v ~/.localpibox/state:/home/dev/.pi:Z \
-    -v ~/.localpibox/agent-browser:/home/dev/.agent-browser:Z \
+    -v /path/to/your/project:/home/lpb/workspace/myproject:Z \
+    -v ~/.localpibox/state:/home/lpb/.pi:Z \
+    -v ~/.localpibox/agent-browser:/home/lpb/.agent-browser:Z \
     -e ED_PORT=3000 \
     ghcr.io/localpibox/devstack:latest
 
@@ -46,9 +46,9 @@ podman run -d --name localpibox --network host --userns keep-id \
 ```bash
 # Run and get a shell inside the container
 podman run -it --name localpibox --network host --userns keep-id \
-    -v /path/to/your/project:/home/dev/workspace/myproject:Z \
-    -v ~/.localpibox/state:/home/dev/.pi:Z \
-    -v ~/.localpibox/agent-browser:/home/dev/.agent-browser:Z \
+    -v /path/to/your/project:/home/lpb/workspace/myproject:Z \
+    -v ~/.localpibox/state:/home/lpb/.pi:Z \
+    -v ~/.localpibox/agent-browser:/home/lpb/.agent-browser:Z \
     -e ED_PORT=3000 \
     ghcr.io/localpibox/devstack:latest
 ```
@@ -88,9 +88,9 @@ flowchart TB
 ```
 
 Mount structure:
-- Host: `$PROJECT → /home/dev/workspace/myproject/`
-- Host: `~/.localpibox/state → /home/dev/.pi` (persistent agent state)
-- Host: `~/.localpibox/agent-browser → /home/dev/.agent-browser` (browser sessions)
+- Host: `$PROJECT → /home/lpb/workspace/myproject/`
+- Host: `~/.localpibox/state → /home/lpb/.pi` (persistent agent state)
+- Host: `~/.localpibox/agent-browser → /home/lpb/.agent-browser` (browser sessions)
 - Host: `Lemonade (:13305) → 127.0.0.1:13305` (host network mode)
 
 ## Commands Available Inside Container
@@ -121,9 +121,9 @@ podman exec -it localpibox update --extensions
 ```bash
 # Run with any project folder
 podman run -d --name localpibox --network host --userns keep-id \
-    -v /home/user/projects/myproject:/home/dev/workspace/myproject:Z \
-    -v ~/.localpibox/state:/home/dev/.pi:Z \
-    -v ~/.localpibox/agent-browser:/home/dev/.agent-browser:Z \
+    -v /home/user/projects/myproject:/home/lpb/workspace/myproject:Z \
+    -v ~/.localpibox/state:/home/lpb/.pi:Z \
+    -v ~/.localpibox/agent-browser:/home/lpb/.agent-browser:Z \
     ghcr.io/localpibox/devstack:latest
 ```
 
@@ -135,9 +135,9 @@ The project mounts at `/workspace/myproject/` so tools see the correct project n
 # First project
 podman run -d --name localpibox --network host --userns keep-id \
     -e ED_PORT=3000 \
-    -v /path/to/project-a:/home/dev/workspace/project-a:Z \
-    -v ~/.localpibox/state:/home/dev/.pi:Z \
-    -v ~/.localpibox/agent-browser:/home/dev/.agent-browser:Z \
+    -v /path/to/project-a:/home/lpb/workspace/project-a:Z \
+    -v ~/.localpibox/state:/home/lpb/.pi:Z \
+    -v ~/.localpibox/agent-browser:/home/lpb/.agent-browser:Z \
     ghcr.io/localpibox/devstack:latest
 # → http://localhost:3000
 
@@ -147,9 +147,9 @@ podman rm localpibox
 
 podman run -d --name localpibox --network host --userns keep-id \
     -e ED_PORT=3001 \
-    -v /path/to/project-b:/home/dev/workspace/project-b:Z \
-    -v ~/.localpibox/state:/home/dev/.pi:Z \
-    -v ~/.localpibox/agent-browser:/home/dev/.agent-browser:Z \
+    -v /path/to/project-b:/home/lpb/workspace/project-b:Z \
+    -v ~/.localpibox/state:/home/lpb/.pi:Z \
+    -v ~/.localpibox/agent-browser:/home/lpb/.agent-browser:Z \
     ghcr.io/localpibox/devstack:latest
 # → http://localhost:3001
 ```
@@ -358,9 +358,9 @@ podman rm localpibox
 # Run with new port
 podman run -d --name localpibox --network host --userns keep-id \
     -e ED_PORT=8080 \
-    -v /path/to/project:/home/dev/workspace/myproject:Z \
-    -v ~/.localpibox/state:/home/dev/.pi:Z \
-    -v ~/.localpibox/agent-browser:/home/dev/.agent-browser:Z \
+    -v /path/to/project:/home/lpb/workspace/myproject:Z \
+    -v ~/.localpibox/state:/home/lpb/.pi:Z \
+    -v ~/.localpibox/agent-browser:/home/lpb/.agent-browser:Z \
     ghcr.io/localpibox/devstack:latest
 # → http://localhost:8080
 ```
@@ -386,9 +386,9 @@ podman exec -it localpibox update --extensions
 podman pull ghcr.io/localpibox/devstack:latest
 podman stop localpibox && podman rm localpibox
 podman run -d --name localpibox --network host --userns keep-id \
-    -v /path/to/project:/home/dev/workspace/myproject:Z \
-    -v ~/.localpibox/state:/home/dev/.pi:Z \
-    -v ~/.localpibox/agent-browser:/home/dev/.agent-browser:Z \
+    -v /path/to/project:/home/lpb/workspace/myproject:Z \
+    -v ~/.localpibox/state:/home/lpb/.pi:Z \
+    -v ~/.localpibox/agent-browser:/home/lpb/.agent-browser:Z \
     ghcr.io/localpibox/devstack:latest
 ```
 

doc/ARCHITECTURE.md

@@ -6,11 +6,11 @@ The system uses a **single image** pulled with `lpb` or direct podman/docker:
 
 ```bash
 podman run -it --network host --userns keep-id \
-  -v /path/to/project:/home/dev/workspace/<project>:Z \
+  -v /path/to/project:/home/lpb/workspace/<project>:Z \
   ghcr.io/localpibox/devstack:latest
 ```
 
-- **Bind mount** for workspace (`$PROJECT:/home/dev/workspace/<project>:Z`)
+- **Bind mount** for workspace (`$PROJECT:/home/lpb/workspace/<project>:Z`)
 - **`network_mode: host`** for direct host service access (Lemonade)
 - **User namespace** (`--userns keep-id` for podman, no-op for docker)
 - **First-run init** in `start.sh` (directories, config sync, npm config)
@@ -23,7 +23,7 @@ podman run -it --network host --userns keep-id \
 | Item | Status | Notes |
 |------|--------|-------|
 | UID/GID Mismatch | **Resolved** | `--userns keep-id` (podman) / `--user=1000` (docker) |
-| Persistent State | **Resolved** | Bind mount `~/.localpibox/state:/home/dev/.pi:Z` |
+| Persistent State | **Resolved** | Bind mount `~/.localpibox/state:/home/lpb/.pi:Z` |
 | Docker Compose removed | **Resolved** | Single image + `lpb` is canonical |
 | Extension updates | **Resolved** | `pi update --extensions` at every boot — installs missing, upgrades stale |
 | Image size | **Resolved** | Extensions installed at runtime (not baked in) — saves ~250MB |
@@ -52,8 +52,8 @@ flowchart TB
             B5["Support tools"]
         end
         subgraph Runtime["Runtime (every boot)"]
-            R1["/home/dev/workspace"]
-            R2["/home/dev/.pi"]
+            R1["/home/lpb/workspace"]
+            R2["/home/lpb/.pi"]
             R3["pi-powerline-footer"]
             R4["pi-mcp-adapter"]
             R5["pi-subagents"]
@@ -69,9 +69,9 @@ flowchart TB
 ```
 
 Mount structure:
-- Host: `$PROJECT → /home/dev/workspace/<project>/`
-- Host: `~/.localpibox/state → /home/dev/.pi` (persistent agent state, skills, agents)
-- Host: `~/.localpibox/agent-browser → /home/dev/.agent-browser` (browser sessions)
+- Host: `$PROJECT → /home/lpb/workspace/<project>/`
+- Host: `~/.localpibox/state → /home/lpb/.pi` (persistent agent state, skills, agents)
+- Host: `~/.localpibox/agent-browser → /home/lpb/.agent-browser` (browser sessions)
 
 ## Extension Update Flow
 
@@ -115,9 +115,9 @@ lpb /path/to/project --port 8080  # Custom editor port
 ### Manual podman command
 
 Mount structure:
-- Host: `$PROJECT → /home/dev/workspace/<project>/`
-- Host: `~/.localpibox/state → /home/dev/.pi` (persistent agent state)
-- Host: `~/.localpibox/agent-browser → /home/dev/.agent-browser` (browser sessions)
+- Host: `$PROJECT → /home/lpb/workspace/<project>/`
+- Host: `~/.localpibox/state → /home/lpb/.pi` (persistent agent state)
+- Host: `~/.localpibox/agent-browser → /home/lpb/.agent-browser` (browser sessions)
 
 ## Remaining Risks