chore(env): retire LPB_MAX_TOKENS_CONTEXT_RATIO chain

Response ceilings are per-model now (maxTokens in the lemonade-pi-plugin
model catalog — companion plugin commit b396890). The ratio env was dead
in the plugin (read as DEFAULT_MAX_TOKENS_CONTEXT_RATIO, never set) and is
removed end-to-end:

- lpb.conf.env / .env.example: variable + example block removed
  (.env local file updated separately)
- start.sh: bridge name, bare fallback, debug line removed
- lpb.py: container env export removed
- build.py: REQUIRED_CONF_VARS emptied, build-arg removed
- tests: sample conf content updated
- doc/fork-improvements.md: Configuration section rewritten

Containers built before this change keep the baked env var until rebuild
— harmless, nothing reads it anymore.

Author: lpb-docs

.env.example

@@ -67,17 +67,11 @@ LPB_AGENT_BROWSER_IDLE_TIMEOUT_MS=300000
 # OpenRouter API key (overflow provider — not needed with Lemonade)
 # LPB_OPENROUTER_API_KEY=
 
-# Max tokens as a fraction of context window (lemonade-pi-plugin).
-# Computed as: max_tokens = context_window * LPB_MAX_TOKENS_CONTEXT_RATIO
-# Default: 0.06 (6 %) — reduced from 0.125 for Qwen thinking models.
-# At 0.125, Qwen thinking models generate 10-20k-token thinking blocks that
-# push prompt+max_tokens past the 262k window limit, causing overflow errors.
-# 0.06 × 262k = ~15.7k maxTokens — leaves room for thinking blocks within window.
-# Examples:
-#   0.06   → 262K context → 15.7K max tokens
-#   0.125  → 262K context → 32.8K max tokens (may overflow with thinking)
-#   0.20   → 262K context → 52.4K max tokens
-# LPB_MAX_TOKENS_CONTEXT_RATIO=0.06
+# Response ceilings are per-model now — the `maxTokens` field in the
+# lemonade-pi-plugin model catalog (~/.pi/agent/model-params.json). The old
+# global LPB_MAX_TOKENS_CONTEXT_RATIO was retired 2026-09-02 (exact values
+# per model, no formula — see lemonade-pi-plugin/docs/qwen-thinking-
+# mainstream-pi.md §5.0).
 
 # Capture outgoing provider payloads (lemonade-pi-plugin) — ALL models.
 # 1 = the plugin logs one JSON line per request (tuned view for catalogued

doc/fork-improvements.md

@@ -120,18 +120,20 @@ network calls. Triggered on login, refresh, and `/lemonade change-ctx`.
 
 ### Configuration
 
-| Constant | Value | Purpose |
+The response ceiling (`max_completion_tokens`) is the **per-model
+`maxTokens` catalog field** in the lemonade-pi-plugin model-params catalog
+(`~/.pi/agent/model-params.json` + the plugin-shipped tier) — an exact token
+value per wire model id, applied at model sync. The former ctx-ratio design
+(`DEFAULT_MAX_TOKENS_CONTEXT_RATIO` 0.125, `QWEN_REASONING_MAX_TOKENS_CONTEXT_RATIO`
+0.06, the 16384 clamp, and the `LPB_MAX_TOKENS_CONTEXT_RATIO` env chain)
+was retired 2026-09-02: the plugin's env read was dead (set by nothing), the
+protective work was done by the clamp anyway, and six explicit numbers are
+more auditable than a formula.
+
+| Model | maxTokens | Why |
 |---|---|---|
-| `DEFAULT_MAX_TOKENS_CONTEXT_RATIO` | `0.125` | Non-reasoning Qwen models |
-| `QWEN_REASONING_MAX_TOKENS_CONTEXT_RATIO` | `0.06` | Reasoning models (thinking headroom) |
-| `QWEN_REASONING_BUDGET_TOKENS` | `0` | Soft-capped thinking (prevents runaway) |
-
-### Why the Ratios Matter
-
-| Model Type | Ratio | 262k Context → maxTokens | Why |
-|---|---|---|---|
-| Reasoning (Qwen MTP) | `0.06` | ~15.7k | Thinking blocks consume 10-20k tokens |
-| Non-reasoning (Qwen) | `0.125` | ~32k | Standard ratio, no thinking overhead |
+| Qwen thinking models (27B/35B) | `16384` | Thinking headroom at the 262k window (old formula + clamp landed here) |
+| Small / non-Qwen models | `4096` | Default response cap (matches the former fallback) |
 
 ---
 

lpb.conf.env

@@ -29,12 +29,6 @@ LPB_LEMONADE_BASE_URL=http://127.0.0.1:13305/v1
 # OpenRouter overflow provider (not needed with Lemonade)
 LPB_OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
 
-# ─── Context Window ─────────────────────────────────────────────────────
-# max_tokens = context_window * LPB_MAX_TOKENS_CONTEXT_RATIO
-# Default: 0.06 (6%) — reduced from 0.125 for Qwen thinking models.
-# Prevents overflow when thinking blocks push prompt+max_tokens past 262k.
-LPB_MAX_TOKENS_CONTEXT_RATIO=0.06
-
 # ─── Persistence ────────────────────────────────────────────────────────
 # Launcher-time host state directory → bind-mounted into the container at
 # /home/lpb/.pi (the Pi config home). Persists across container rebuilds.

scripts/lpb.py

@@ -1763,7 +1763,6 @@ def _build_run_env(mount_path: str) -> list[str]:
         # has no need for it — start.sh uses its own defaults. Passing it here
         # would pollute .devstack-env and break future host runs.
         f"LPB_EXA_API_KEY={os.environ.get('LPB_EXA_API_KEY', os.environ.get('EXA_API_KEY', ''))}",
-        f"LPB_MAX_TOKENS_CONTEXT_RATIO={os.environ.get('LPB_MAX_TOKENS_CONTEXT_RATIO', _conf_cfg.get('LPB_MAX_TOKENS_CONTEXT_RATIO', '0.06'))}",
     ]
     # Lemonade model server — resolved by the unified setup preflight in
     # cmd_run (all modes): interactive wizard before a fresh start, or

scripts/test_localpibox_build.py

@@ -33,10 +33,9 @@ def test_build_load_env_success(tmpdir):
         "LPB_NODE_VERSION=24\n"
         "LPB_VSCODIUM_VERSION=1.126.04524\n"
     )
-    (tmpdir / "lpb.conf.env").write_text("LPB_MAX_TOKENS_CONTEXT_RATIO=0.06\n")
+    (tmpdir / "lpb.conf.env").write_text("# no required conf vars (ratio retired)\n")
     env = build.load_build_env(tmpdir.path)
     assert env["LPB_IMAGE_CLI"] == "ghcr.io/lpb-stack/devstack:cli"
-    assert env["LPB_MAX_TOKENS_CONTEXT_RATIO"] == "0.06"
 
 
 def test_build_load_env_missing_file(tmpdir):
@@ -50,7 +49,7 @@ def test_build_load_env_missing_file(tmpdir):
 
 def test_build_load_env_missing_var(tmpdir):
     for name in ("lpb.stack.env", "lpb.conf.env"):
-        (tmpdir / name).write_text("LPB_MAX_TOKENS_CONTEXT_RATIO=0.06\n")
+        (tmpdir / name).write_text("# no required conf vars (ratio retired)\n")
     try:
         build.load_build_env(tmpdir.path)
         assert False, "should raise RuntimeError"
@@ -64,7 +63,7 @@ def test_build_load_env_expands_home(tmpdir):
         "LPB_CONFIG_FORK=c\nLPB_CONFIG_REF=m\nLPB_NODE_VERSION=n\nLPB_VSCODIUM_VERSION=v\n"
     )
     (tmpdir / "lpb.conf.env").write_text(
-        "LPB_MAX_TOKENS_CONTEXT_RATIO=0.06\nLPB_STATE_DIR=${HOME}/.lpb-stack/state\n"
+        "LPB_STATE_DIR=${HOME}/.lpb-stack/state\n"
     )
     env = build.load_build_env(tmpdir.path)
     assert env["LPB_STATE_DIR"] == os.path.expanduser("~") + "/.lpb-stack/state"
@@ -75,7 +74,6 @@ def test_build_build_args_with_fake_git(tmpdir):
         "LPB_PI_VERSION": "0.84.4",
         "LPB_CONFIG_FORK": "cfg", "LPB_CONFIG_REF": "main",
         "LPB_NODE_VERSION": "24", "LPB_VSCODIUM_VERSION": "v",
-        "LPB_MAX_TOKENS_CONTEXT_RATIO": "0.06",
         "LPB_IMAGE_CLI": "cli", "LPB_IMAGE_WEB": "web",
     }
     (tmpdir / "VERSION").write_text("0.9.9-test\n")
@@ -99,7 +97,6 @@ def test_build_build_args_git_fail(tmpdir):
         "LPB_PI_VERSION": "0.84.4",
         "LPB_CONFIG_FORK": "cfg", "LPB_CONFIG_REF": "main",
         "LPB_NODE_VERSION": "24", "LPB_VSCODIUM_VERSION": "v",
-        "LPB_MAX_TOKENS_CONTEXT_RATIO": "0.06",
         "LPB_IMAGE_CLI": "cli", "LPB_IMAGE_WEB": "web",
     }
     runner = _fake_runner({"ls-remote": ("", 128), "rev-parse": ("", 128)})

support/build.py

@@ -38,7 +38,9 @@
     "LPB_NODE_VERSION",
     "LPB_VSCODIUM_VERSION",
 ]
-REQUIRED_CONF_VARS = ["LPB_MAX_TOKENS_CONTEXT_RATIO"]
+# No required conf vars (LPB_MAX_TOKENS_CONTEXT_RATIO retired 2026-09-02 —
+# response ceilings are per-model in the lemonade-pi-plugin catalog now).
+REQUIRED_CONF_VARS = []
 ENV_FILES = ["lpb.stack.env", "lpb.conf.env"]
 
 # Mainstream pi repo — used only to resolve the source sha of the pinned
@@ -119,7 +121,6 @@ def build_args(
         "--build-arg", f"CONFIG_REF={env['LPB_CONFIG_REF']}",
         "--build-arg", f"NODE_VERSION={env['LPB_NODE_VERSION']}",
         "--build-arg", f"VSCODIUM_VERSION={env['LPB_VSCODIUM_VERSION']}",
-        "--build-arg", f"LPB_MAX_TOKENS_CONTEXT_RATIO={env['LPB_MAX_TOKENS_CONTEXT_RATIO']}",
         "--build-arg", f"LPB_VERSION={lpb_version}",
         "--build-arg", f"IMAGE_REVISION={git_head_short(root, runner=runner)}",
         "--build-arg", f"IMAGE_BUILT={now.strftime('%Y-%m-%dT%H:%M:%SZ')}",

support/start.sh

@@ -138,7 +138,6 @@ BARE_NAMES=(
     HOST
     CONNECTION_TOKEN
     DEVCONTAINER_WORKSPACE_DIR
-    MAX_TOKENS_CONTEXT_RATIO
     GITHUB_TOOLSETS
     AGENT_BROWSER_ARGS
     AGENT_BROWSER_MAX_OUTPUT
@@ -155,7 +154,6 @@ declare -A BARE_FALLBACKS=(
     [HOST]="0.0.0.0"
     [CONNECTION_TOKEN]="$(cat /proc/sys/kernel/random/uuid 2>/dev/null || uuidgen 2>/dev/null || python3 -c 'import uuid;print(uuid.uuid4())')"
     [DEVCONTAINER_WORKSPACE_DIR]="/home/lpb/workspace"
-    [MAX_TOKENS_CONTEXT_RATIO]="0.06"
     [GITHUB_TOOLSETS]="all"
     [AGENT_BROWSER_ARGS]="--no-sandbox,--no-first-run,--disable-gpu,--disable-crashpad"
     [AGENT_BROWSER_MAX_OUTPUT]="4000"
@@ -213,7 +211,6 @@ debug "LEMONADE_BASE_URL=$LEMONADE_BASE_URL"
 debug "WORKSPACE_DIR=$WORKSPACE_DIR"
 debug "ED_PORT=$ED_PORT"
 debug "EDITOR_HOST=$HOST"
-debug "MAX_TOKENS_CONTEXT_RATIO=$MAX_TOKENS_CONTEXT_RATIO"
 
 # ─── 2. RESOLVE PROJECT DIRECTORY & LOAD .ENV ──────────────────────────────
 # The project is a subdirectory of the workspace (e.g. "/home/lpb/workspace/<project>")