lobes-cli 0.68.4__tar.gz → 0.69.2__tar.gz

lobes_cli-0.69.2/.devague/current

@@ -0,0 +1 @@
+targeted-ops-and-honest-streams

lobes_cli-0.69.2/.devague/frames/targeted-ops-and-honest-streams.json

@@ -0,0 +1,276 @@
+{
+  "slug": "targeted-ops-and-honest-streams",
+  "title": "targeted ops and honest streams",
+  "schema_version": 5,
+  "status": "drafting",
+  "created": "2026-08-29T12:18:43Z",
+  "updated": "2026-08-29T12:19:55Z",
+  "claims": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "lobes keeps two promises it currently breaks: a targeted lobe operation touches only what it names, and a streamed or proxied answer is honest about what it is \u2014 every SSE relay ends with a terminal frame and a closed socket even when its upstream dies, and a proxied role advertises the hosting peer's own ready and context rather than a locally-guessed one.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c2",
+      "kind": "requirement",
+      "text": "compose_service_argv's up branch gains --no-deps: lobes/runtime/_compose.py:769-782 builds ['docker','compose',*files,'up','-d',*services] and its own docstring already promises 'only these are (re)started ... without disturbing the rest of the fleet' \u2014 grep for no-deps/no_deps across lobes/ returns nothing, so the docstring is the spec and the argv is the defect. lobes/cli/_commands/up.py:231 is the single caller and renders its dry-run PLAN from the same argv, so the printed plan becomes truthful in the same change.",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c3",
+      "kind": "requirement",
+      "text": "the fleet template's gateway depends_on stops being an unconditional hard edge: lobes/templates/fleet/docker-compose.yml:1706-1710 lists vllm-primary/vllm-multimodal/vllm-embed/vllm-rerank, its own adjacent comment says 'Start order only \u2014 the gateway tolerates a backend still loading ... so it must not block on backend health', and lobes/cli/_commands/init.py:230 already !resets exactly this attribute for a role-dropping shape \u2014 so the edge is already known-droppable.",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c4",
+      "kind": "requirement",
+      "text": "lobes gains a first-class gateway update path: lobes/cli/_commands/up.py:92 sets TARGETS = roles.ROLES + (colleague-stack,), so 'gateway' is not an addressable target and the operator need ('reinstall the gateway at a new MODEL_GEAR_VERSION, touch nothing else') has no verb \u2014 which is why issue 222 was hit through a hand-written docker compose up -d --build gateway.",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c5",
+      "kind": "requirement",
+      "text": "_relay_streaming terminates the client stream on an upstream failure: lobes/gateway/server.py:3442-3457 loops resp.upstream.read(_CHUNK) -> wfile.write(frame_chunk(chunk)) with no try/except, so an exception from either side skips both CHUNK_TERMINATOR and any terminal SSE frame; _Upstream.read (server.py:482) is a bare http.client read1 that can raise OSError/HTTPException mid-stream.",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c6",
+      "kind": "requirement",
+      "text": "a proxied role's advertised ready and context come from the hosting peer's own /capabilities, not from local data: lobes/roles.py:682-711 derives context from _served_context(role, env, native_context) over the LOCAL .env plus the catalog's native_max_model_len (1048576 for the Lightning entry), and lobes/gateway/_readiness.py:212-266 probe_peer_ready only checks that the peer's /v1/models lists served_name \u2014 which a box forwarding the alias (ASSOCIATE_SERVED_NAME) can never satisfy, yielding the reported ready:false/context:1048576 against the Orin's own ready:true/context:128000.",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c7",
+      "kind": "assumption",
+      "text": "probe_audio_peer_ready (lobes/gateway/_readiness.py:322-341) is the existing precedent for reading a peer's GET /capabilities and trusting roles[role].ready \u2014 the core-role relay is that same shape widened to carry context, not a new mechanism.",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c8",
+      "kind": "boundary",
+      "text": "the shape override contract is untouched: lobes/cli/_commands/init.py:187-231 renders docker-compose.shape.yml parking dropped services in the inert shape-dropped profile AND emitting 'depends_on: !reset null' on the gateway; tests/test_shape_goldens.py and tests/test_init_shape.py pin that text, so a base-template depends_on change must leave the override renderable and its goldens honest (a !reset of an absent attribute is legal but the comment prose around it would become false).",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c9",
+      "kind": "boundary",
+      "text": "the stop branch of compose_service_argv stays as it is: docker compose stop does not walk depends_on, so --no-deps belongs on the up branch only \u2014 the issue itself names this asymmetry as why the defect went unnoticed.",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c10",
+      "kind": "boundary",
+      "text": "the per-heavy-lobe depends_on edges are NOT in scope: vllm-muse (docker-compose.yml:1245), vllm-worker (:1354) and vllm-associate (:1602) each wait on vllm-embed/vllm-rerank service_healthy as a MEASURED mitigation for the Thor unified-memory first-boot race (2026-07-17, docs/machine-profiles.md) \u2014 only the gateway's edge is the defect.",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c11",
+      "kind": "non_goal",
+      "text": "issue 220 part 4 (bursts of 29x POST /tokenize 401 every ~2 min) is not fixed here: the issue itself states the fix is on the resident side (an older spark-colleague mesh resident without the gateway key), and nothing under lobes/gateway/ is misbehaving \u2014 a 401 on an unauthenticated POST is the #127 inbound gate working.",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c12",
+      "kind": "non_goal",
+      "text": "issue 220 part 3 (reranker calibration \u2014 distractors scoring 0.72-0.77, a NOTICE sentence out-ranking a toolbatch sentence) is not fixed here: it is a served-prompt-template/measurement investigation against Qwen3-Reranker-0.6B's model card, with no defect localised in lobes yet, and the reporter's own verdict is 'usable for top-k ordering, not thresholds'.",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    },
+    {
+      "id": "c13",
+      "kind": "boundary",
+      "text": "no live-box validation is claimed: the #108 rule in CLAUDE.md forbids doc, support-table or lobes capabilities output claiming validation without an acceptance transcript under docs/evidence/, and the boxes this was observed on (spark, the Thor peer, the Orin) are not being re-booted by this change \u2014 every claim here is offline-testable or stays UNVALIDATED.",
+      "origin": "llm",
+      "status": "proposed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": [],
+      "instruction": "",
+      "revisions": []
+    }
+  ],
+  "open_vagueness": [
+    {
+      "id": "v1",
+      "text": "the reported symptom (client hangs, SSE socket ESTABLISHED, no terminal frame) is not fully explained by the traceback in the issue: a BrokenPipeError on wfile.write means the CLIENT already went away, yet the client reported still waiting \u2014 so there may be a second failure mode (the JSONDecodeError traceback, or a pre-relay path) that the _relay_streaming fix alone does not close.",
+      "kind": "unknown_nonblocking",
+      "claim_id": null,
+      "resolved": false,
+      "resolution": "",
+      "resolution_claim_id": null
+    },
+    {
+      "id": "v2",
+      "text": "whether an infeasible-but-PROXIED role should relay the peer's context verbatim or a min(local ceiling, peer context) \u2014 a caller that trusts a relayed 128000 is right today, but the value is the peer's, and this box cannot honour it if the proxy is later withdrawn.",
+      "kind": "unknown_nonblocking",
+      "claim_id": null,
+      "resolved": false,
+      "resolution": "",
+      "resolution_claim_id": null
+    }
+  ],
+  "scope_entries": [
+    {
+      "id": "s1",
+      "surface": "lobes/runtime/_compose.py:769-782 (compose_service_argv)",
+      "finding": "the up branch emits 'up -d <services>' with no --no-deps while its docstring promises fleet isolation; grep -rn 'no-deps|no_deps' lobes/ returns nothing",
+      "seeds": [
+        "c2",
+        "c9"
+      ]
+    },
+    {
+      "id": "s2",
+      "surface": "lobes/cli/_commands/up.py (TARGETS, ROLE_SERVICE, _resolve)",
+      "finding": "the single caller of compose_service_argv (line 231); TARGETS at line 92 is roles.ROLES + colleague-stack, so 'gateway' is not an addressable target; ROLE_SERVICE maps ten roles to services, gateway absent",
+      "seeds": [
+        "c2",
+        "c4"
+      ]
+    },
+    {
+      "id": "s3",
+      "surface": "lobes/templates/fleet/docker-compose.yml (gateway service, line ~1690-1712)",
+      "finding": "gateway depends_on lists all four default core lanes unconditionally, annotated 'Start order only \u2014 the gateway ... must not block on backend health'; the muse/worker/associate lanes at 1245/1354/1602 carry a DIFFERENT, measured depends_on on embed+rerank service_healthy",
+      "seeds": [
+        "c3",
+        "c10"
+      ]
+    },
+    {
+      "id": "s4",
+      "surface": "lobes/cli/_commands/init.py:143-231 (SHAPE_DROPPED_PROFILE, render_shape_override)",
+      "finding": "a role-dropping shape already parks dropped services in the inert 'shape-dropped' profile and emits 'depends_on: !reset null' on the gateway \u2014 so the base edge is known-droppable, and its prose/goldens are the constraint on changing the base",
+      "seeds": [
+        "c3",
+        "c8"
+      ]
+    },
+    {
+      "id": "s5",
+      "surface": "lobes/gateway/server.py:432-436, 482-495, 3442-3457 (_relay_streaming, _Upstream.read, frame_chunk)",
+      "finding": "the relay loop has no exception handling around either the upstream read1 or the client wfile.write, so a mid-stream failure skips CHUNK_TERMINATOR entirely and emits no terminal SSE frame",
+      "seeds": [
+        "c5"
+      ]
+    },
+    {
+      "id": "s6",
+      "surface": "lobes/roles.py:120-170 and 682-711 (ROLE_BACKEND/ROLE_ROLE_HINT, _core_role entry builder)",
+      "finding": "context comes from _served_context over the LOCAL .env plus the catalog native_max_model_len, and associate shares worker's role_hint (one checkpoint, two addresses) \u2014 which is also why the raw model id and 'worker' resolve to the local worker backend and 404 role_infeasible on the proxying box",
+      "seeds": [
+        "c6"
+      ]
+    },
+    {
+      "id": "s7",
+      "surface": "lobes/gateway/_readiness.py:212-266 (probe_peer_ready) and :322-341 (probe_audio_peer_ready)",
+      "finding": "the core-role peer probe asserts the peer's /v1/models lists served_name \u2014 unsatisfiable when the box forwards an alias \u2014 while the AUDIO peer probe already reads the peer's GET /capabilities and trusts roles[role].ready; the audio shape is the precedent to widen",
+      "seeds": [
+        "c6",
+        "c7"
+      ]
+    },
+    {
+      "id": "s8",
+      "surface": "issue 220 parts 3 and 4 as filed",
+      "finding": "part 4 names its own fix as resident-side (an old spark-colleague without the gateway key); part 3 has no defect localised in lobes and asks for a served-prompt-template check against the model card \u2014 neither is a lobes code change today",
+      "seeds": [
+        "c11",
+        "c12"
+      ]
+    },
+    {
+      "id": "s9",
+      "surface": "CLAUDE.md (#108 honesty rule) and docs/evidence/",
+      "finding": "no acceptance transcript may be claimed without a live boot; the boxes in both issue reports are not being re-booted here, so every claim must be offline-testable or explicitly stay UNVALIDATED",
+      "seeds": [
+        "c13"
+      ]
+    },
+    {
+      "id": "s10",
+      "surface": "tests/ (test_cli_up.py, test_compose_chain.py, test_shape_goldens.py, test_init_shape.py, test_gateway_readiness.py, test_gateway_capabilities.py, test_gateway_proxy.py)",
+      "finding": "existing offline suites already cover the argv, the compose chain, the shape override goldens, the peer probes and the capabilities payload \u2014 issue 222's requested guard tests (argv contains --no-deps; an infeasible role is never a started dependency) land in files that already exist",
+      "seeds": [
+        "c2",
+        "c3"
+      ]
+    }
+  ],
+  "lapses": []
+}

{lobes_cli-0.68.4 → lobes_cli-0.69.2}/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.69.2] - 2026-08-29
+
+### Fixed
+
+- An inbound auth rejection now logs its source and the reason it failed, and repeats from one source collapse to one line per 60s instead of flooding the log (issue #228). The 401 response is unchanged and still distinguishes nothing — the caller must not learn missing vs. malformed vs. wrong.
+
+## [0.69.1] - 2026-08-29
+
+### Fixed
+
+- The streamed relay also treats a `ValueError` from the upstream read as an upstream failure, so a malformed chunked body cannot skip the terminal SSE frames (PR #229 review).
+- `cmd_up` and `build_role_registry` were split into named helpers (`_audio_overlay_required`, `_resolve_build`, `_role_signals`) to stay under the cognitive-complexity gate.
+
+## [0.69.0] - 2026-08-29
+
+### Added
+
+- `lobes up gateway` (and `--build`) — a first-class path to restart or re-image the gateway alone at a new `MODEL_GEAR_VERSION` (issue #222).
+
+### Fixed
+
+- `lobes up <role>` now runs with `--no-deps` and the fleet gateway declares no `depends_on`, so a targeted start can no longer recreate the whole fleet or boot a lane the box declares infeasible (issue #222).
+- A streamed `/v1/chat/completions` relay always terminates the client stream: an upstream that dies mid-stream now yields an SSE error event, `data: [DONE]` and the chunked terminator, and a client that hung up is logged instead of leaving a wedged socket (issue #220).
+- A proxied role advertises the hosting peer's own `ready` and `context`, read from the peer's `GET /capabilities`, instead of a locally-guessed catalog ceiling and an unsatisfiable `/v1/models` check (issue #220).
+
 ## [0.68.4] - 2026-08-29
 
 ### Fixed

{lobes_cli-0.68.4 → lobes_cli-0.69.2}/CLAUDE.md

@@ -238,7 +238,14 @@ busy — the former degrade-to-`minor` substitution path was removed outright,
 so there is no cheaper-rung fallback for any of the four); an explicit
 `hand` request (or its `minor`/`cheap` spellings) is the servable floor and is
 always served regardless of pressure. `lobes status --pressure` shows the current busy/warm state.
-Start/stop one role at a time with `lobes up <role>` (or the
+Start/stop one role at a time with `lobes up <role>` — which since issue #222
+actually isolates: every `up` carries `--no-deps` and the base compose gives
+the gateway no `depends_on` at all, because `docker compose up -d <service>`
+walks that list and a gateway-only restart was therefore recreating every heavy
+lane (measured live on the Thor 2026-08-28, including starting a lane the box
+declares `MULTIMODAL_FEASIBLE=false`). `gateway` is now an `up` TARGET too (not
+a role): `lobes up gateway --build --apply` re-images the front at a new
+`MODEL_GEAR_VERSION` without touching the lobes behind it. Or the
 seven-default-role bundle, `lobes up colleague-stack` — `muse` and `worker` are
 deliberately excluded from the bundle, both being opt-in-hosted, while `hand`
 IS included, being default-hosted and un-gated; `lobes up muse` works on
@@ -704,8 +711,20 @@ stays byte-identical to the pre-proxy contract.
 **Live as of 2026-07-31:** the DGX Spark (`spark-lobe`) proxies TWO roles —
 `senses` → the AGX Orin and `worker` → the Jetson AGX Thor — so a caller
 addresses either on the Spark's own gateway and never dials the peer box.
-Both answer 200 with `X-Lobes-Proxied-By`, image input included. Note a proxied
-role reports `feasible: false` **by design** (it means "this box does not *host*
+Both answer 200 with `X-Lobes-Proxied-By`, image input included. **A proxied
+role's `ready` and `context` are the PEER's own advert (issue #220):** the
+background probe reads the peer's `GET /capabilities` and relays that role
+entry, falling back to the old `/v1/models` served-id check only for a peer
+with no such entry. Both halves fixed a measured lie — on the Spark,
+2026-08-27, `associate` advertised `ready:false, context:1048576` against an
+Orin reporting `ready:true, context:128000` — with two distinct causes: the
+`/v1/models` check is unsatisfiable for a box forwarding an ALIAS (which
+`associate` must do, sharing a checkpoint with `worker`), and a role this box
+does not host has no `<PREFIX>_MAX_MODEL_LEN` to read, so context fell through
+to the catalog's native ceiling. That collision is also why **role-name
+addressing (`model=associate`) is the documented proxied path** — the raw
+checkpoint id is ambiguous and resolves to the local `worker` lane. Note a
+proxied role reports `feasible: false` **by design** (it means "this box does not *host*
 it", not "you cannot use it here"); `proxied: true` + `hosted_by` + `ready` are
 the fields that say it is usable, and `loaded` is a *wiring* fact, not a
 running one. See `docs/gateway-fleet.md#proxy-lobes-the-third-lobe-state-opt-in`

{lobes_cli-0.68.4 → lobes_cli-0.69.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lobes-cli
-Version: 0.68.4
+Version: 0.69.2
 Summary: lobes — run, assess, and switch the local vLLM model.
 Project-URL: Homepage, https://github.com/agentculture/lobes-cli
 Project-URL: Issues, https://github.com/agentculture/lobes-cli/issues

{lobes_cli-0.68.4 → lobes_cli-0.69.2}/docs/colleague-stack.md

@@ -661,19 +661,51 @@ carries `hosted_by` at most, never `proxied`).
 touching the rest of the fleet:
 
 ```bash
-lobes up cortex --apply             # docker compose up -d vllm-primary
-lobes up senses --apply             # docker compose up -d vllm-multimodal
-lobes up muse --apply               # docker compose up -d vllm-muse (muse-hosting shape only — currently no box hosts one, see the dormant callout above)
-lobes up worker --apply             # docker compose up -d vllm-worker (verb wired; live on the Spark since d1, errors helpfully off any other non-hosting box)
-lobes up embedder --apply           # docker compose up -d vllm-embed
-lobes up reranker --apply           # docker compose up -d vllm-rerank
+lobes up cortex --apply             # docker compose up -d --no-deps vllm-primary
+lobes up senses --apply             # docker compose up -d --no-deps vllm-multimodal
+lobes up muse --apply               # docker compose up -d --no-deps vllm-muse (muse-hosting shape only — currently no box hosts one, see the dormant callout above)
+lobes up worker --apply             # docker compose up -d --no-deps vllm-worker (verb wired; live on the Spark since d1, errors helpfully off any other non-hosting box)
+lobes up embedder --apply           # docker compose up -d --no-deps vllm-embed
+lobes up reranker --apply           # docker compose up -d --no-deps vllm-rerank
 lobes up stt --apply                # requires the --audio overlay
 lobes up tts --apply                # requires the --audio overlay
 lobes up colleague-stack --apply    # the SEVEN default roles at once (requires --audio scaffolded)
+lobes up gateway --apply            # the gateway ALONE (not a role — see below)
+lobes up gateway --build --apply    # ...re-imaged at the current MODEL_GEAR_VERSION
 ```
 
 Dry-run by default (prints the exact `docker compose …` command); `--apply`
-commits. `colleague-stack` is a first-class bundle — the four default fleet
+commits.
+
+### `--no-deps` is what makes "without touching the rest of the fleet" true
+
+**Issue #222.** `docker compose up -d <service>` **walks `depends_on`** and
+(re)creates every dependency, so before #222 this verb's isolation promise was
+documentation only. Hit live on a Jetson AGX Thor 2026-08-28: a gateway-only
+rebuild recreated the resident 27B cortex (a multi-minute reload) *and* started
+`vllm-multimodal` on a box declaring `MULTIMODAL_FEASIBLE=false` with an active
+proxy to a peer — burning the exact GPU budget that declaration exists to
+reclaim, in a unified-memory race against the load it was meant to leave alone.
+
+Every `up` now carries `--no-deps`, and the base compose no longer gives the
+gateway a `depends_on` at all (belt and braces: the flag fixes this CLI, the
+template fixes the hand-written `docker compose` command and every
+lock-restored box). `--down` needs no equivalent — compose `stop` never walks
+`depends_on`, which is exactly why the asymmetry went unnoticed. The dry-run
+PLAN is rendered from the argv that later runs, so the printed command is the
+executed one.
+
+### `gateway` is a target, not a role
+
+`gateway` is deliberately **not** in `lobes.roles.ROLES`, not in the role→service
+map, and not in the `colleague-stack` bundle — it is the stdlib reverse proxy
+*fronting* the roles, not one of them. It is an `up` target because it is the
+service an operator most often needs to touch alone: pure stdlib, rebuilds in
+seconds, and it bakes `MODEL_GEAR_VERSION` into its image, while the lobes
+behind it take minutes and hold tens of GiB. `lobes up gateway --build --apply`
+is the "reinstall the gateway, touch nothing else" operation that had no verb
+before #222 — which is why it was being done by hand, with the consequences
+above. `colleague-stack` is a first-class bundle — the four default fleet
 roles **plus** the audio overlay's `stt`/`tts` — not a compose `profiles:`
 tag, because tagging the already-default-on services with a profile would
 demote them out of the default fleet (a regression). If the audio overlay

{lobes_cli-0.68.4 → lobes_cli-0.69.2}/docs/deployment-shapes.md

@@ -277,10 +277,16 @@ half-served, never silently rerouted:
    docker-compose.shape.yml`, which `lobes fleet up --apply` auto-includes
    when present). It parks each dropped core service in the inert
    `shape-dropped` compose profile — a profile **nothing** activates, so
-   `docker compose up` skips it — and clears the gateway's `depends_on` with
-   the compose `!reset` merge tag (list *replacement* is `!override`; `!reset`
-   is what removes the now-dangling edge to a profile-disabled service).
-   **Requires Docker Compose v2.24+** (the `!reset` tag). The resolved `-f`
+   `docker compose up` skips it. It used to *also* clear the gateway's
+   `depends_on` with the compose `!reset` merge tag, because the base template
+   listed every core lane there and a profile-disabled service left that edge
+   dangling; since **issue #222** the base template declares no gateway
+   `depends_on` at all, so the override no longer patches the gateway and no
+   longer needs Compose v2.24+. (The edge was never a correctness property —
+   the gateway routes and fails over per request — but it *was* a hazard: any
+   gateway start walked it and brought up every heavy lane, dropped or not.
+   Removing it in the base file also covers the hand-scaffolded and
+   lock-restored boxes no shape override reaches.) The resolved `-f`
    chain comes from one builder (#137) and is printable read-only via
    `lobes fleet files` — anything driving `docker compose` by hand (scripts,
    operators) should consume that instead of re-deriving the file list.

{lobes_cli-0.68.4 → lobes_cli-0.69.2}/docs/gateway-fleet.md

@@ -128,8 +128,8 @@ actually activates a template change on a running fleet.
 The gateway adds a second backend **only** when `FALLBACK_URL` or
 `FALLBACK_SERVED_NAME` is set. To add a warm fallback: define a `vllm-fallback`
 service in the fleet compose (mirror `vllm-primary` with the fallback's model /
-quantization / tokenizer / tool-parser), add it to the gateway's `depends_on`,
-set `FALLBACK_URL` + `FALLBACK_SERVED_NAME` on the gateway, and **drop both
+quantization / tokenizer / tool-parser), set `FALLBACK_URL` +
+`FALLBACK_SERVED_NAME` on the gateway, and **drop both
 `*_GPU_MEM_UTIL` values** so they sum well under 1.0. The archived dense Mistral
 fallback config is in git history and
 [`docs/mistral-small-3.2-24b-nvfp4.md`](mistral-small-3.2-24b-nvfp4.md).
@@ -512,6 +512,42 @@ The gate runs *before* the request body is read off the socket, before model
 resolution, and before any upstream connection, so a rejected request costs
 the fleet zero parsing and zero sockets.
 
+**What the rejection LOGS (issue #228).** The response says as little as
+possible; the log says as much as the operator needs, and the asymmetry is
+deliberate — the caller must not learn whether its key was missing, malformed
+or merely wrong (that would make a 401 a key-material oracle), while whoever
+reads their own gateway's stderr needs exactly that to tell a misconfigured
+client from someone guessing. A rejection logs:
+
+```text
+[gateway] auth: rejected POST /tokenize from 172.21.0.1 (no Authorization header)
+```
+
+— the method and path, the **socket peer** (never `X-Forwarded-For`: a
+security log whose attribution field the caller can write is worse than one
+with none), and a reason from a fixed set (`no Authorization header` /
+`not a Bearer credential` / `empty Bearer token` /
+`Bearer token did not match this gateway's key`). No reason string is derived
+from the presented credential or the configured key, so the classification
+cannot leak what it classified.
+
+Repeats from one source **collapse to one line per 60 s**, and the next line
+after that window carries what was suppressed:
+
+```text
+[gateway] auth: rejected POST /tokenize from 172.21.0.1 (no Authorization header) [+28 more from this source in the previous 123s]
+```
+
+Both the diagnostic *and* the ordinary access line are suppressed for a
+collapsed repeat — suppressing only one would leave the flood at its original
+size. This is sized against the measured failure: a client with no key retried
+in bursts of ~29 every ~2 minutes, putting **1190 identical, sourceless,
+reasonless lines** into four hours of a DGX Spark's gateway log and burying
+everything else it had to say. Sources collapse independently, so a second
+address appearing is never hidden by a first one that is already flooding, and
+the tracking table is capped (least-recently-seen evicted) because its keys are
+attacker-chosen.
+
 **Hosting `associate` makes the key non-optional — enforced by `lobes
 doctor`.** The bearer gate above is opt-in fleet-wide, but the `associate`
 lane is the one role whose exposure has already gone wrong in practice. On
@@ -656,16 +692,53 @@ policy when the forward arrives. Shedding here too would gate the role a
 second time, against the wrong box's load.
 
 **`/v1/models` and `GET /capabilities` only advertise what the peer honestly
-serves.** A background thread probes the declared peer's own `GET
-/v1/models` (with the pairwise key, when declared) and lists the proxied id
-on *this* box's `/v1/models` only when the peer's own response actually
-lists it — issue #92 ("advertised implies reachable") extended across a box
-boundary. `GET /capabilities` mirrors this: a proxied role reports
-`"proxied": true` alongside `"hosted_by": "<peer origin>"`, and its `ready`
-reflects the same live peer-probe verdict, never a hardcoded `true`. See
+serves.** A background thread probes the declared peer and lists the proxied
+id on *this* box's `/v1/models` only when the peer honestly serves it —
+issue #92 ("advertised implies reachable") extended across a box boundary. `GET
+/capabilities` mirrors this: a proxied role reports `"proxied": true`
+alongside `"hosted_by": "<peer origin>"`, and its `ready` reflects the live
+peer-probe verdict, never a hardcoded `true`. See
 [`docs/colleague-stack.md`](colleague-stack.md#a-third-role-state-proxied)
 for the role-contract view.
 
+**The advert is the PEER's, not a local guess (issue #220).** That background
+probe reads the peer's own `GET /capabilities` and relays the role entry's
+`ready` **and** `context`. Both halves fix a measured lie. On the DGX Spark,
+2026-08-27, `associate` advertised `ready:false, context:1048576` against an
+Orin reporting `ready:true, context:128000` and serving the seat in 0.6 s:
+
+- *`ready`* — the probe used to require the peer's `/v1/models` to list the
+  id this box forwards. That is unsatisfiable whenever the box forwards an
+  **alias** rather than a raw checkpoint id, which `associate` must do (see
+  below). The `/v1/models` check is **kept as a fallback** for a peer with no
+  `/capabilities` entry for the role — an older lobes gateway, or a bare vLLM
+  someone pointed a peer origin at — so no working deployment loses its
+  signal.
+- *`context`* — a role this box does not host has no
+  `<PREFIX>_MAX_MODEL_LEN` in this box's `.env`, so the local computation fell
+  through to the **catalog's native ceiling**: the checkpoint's maximum, not
+  the window the peer chose to serve. A peer that reports no usable context
+  leaves the local answer exactly as it was.
+
+Only a role in the peer-proxy set reads this channel; a role this box hosts
+always computes its own context from its own `.env`.
+
+**Address a proxied role by its ROLE NAME.** `model=<role>` — `associate`,
+`senses`, `worker` — is the supported way to reach a proxied lane, and for
+some lanes it is the *only* one. Two lanes can share a checkpoint (`worker`
+and `associate` both serve
+`nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-NVFP4`, one checkpoint with two
+public addresses of different authority), so the **raw model id is ambiguous**:
+it resolves to whichever backend this box wires locally, which on a box that
+hosts `worker` and proxies `associate` is the local `worker` — the proxied
+role then 404s `role_infeasible` for the raw id and for the other role's name,
+while `model=associate` routes correctly. This is why such a lane declares
+`ASSOCIATE_SERVED_NAME=associate` (forwarding the alias, not the checkpoint
+id), and in turn why the `/v1/models` readiness check above could never
+succeed for it. Role-name addressing is the documented contract
+([`docs/colleague-stack.md`](colleague-stack.md)); a raw checkpoint id is a
+convenience that only survives while it is unambiguous.
+
 **Default off, byte-identical.** With no `<PREFIX>_PEER_PROXY` set anywhere —
 every deployment that predates this feature, and every referral-only
 deployment today — this branch never fires: every response stays

{lobes_cli-0.68.4 → lobes_cli-0.69.2}/docs/mistral-small-3.2-24b-nvfp4.md

@@ -45,8 +45,10 @@ two-part change (see
 [`docs/gateway-fleet.md` → Adding a fallback](gateway-fleet.md#adding-a-fallback)):
 
 1. **Add a `vllm-fallback` service** to the fleet `docker-compose.yml` (mirror
-   `vllm-primary`) that serves Mistral with its own knobs, and add it to the
-   `gateway` service's `depends_on`:
+   `vllm-primary`) that serves Mistral with its own knobs. Do **not** add it to
+   the `gateway` service's `depends_on` — the gateway deliberately declares
+   none (issue #222): `docker compose up -d gateway` walks `depends_on`, so an
+   edge there turns every gateway restart into a fleet-wide one.
 
    ```yaml
    command:

{lobes_cli-0.68.4 → lobes_cli-0.69.2}/docs/openai-api.md

@@ -24,6 +24,15 @@ request's `model` field. Clients point at the same URL either way.
 | `/capabilities` | GET | gateway | the nine-role Colleague contract (`cortex`/`senses`/`muse`/`worker`/`embedder`/`reranker`/`stt`/`tts`) resolved to live endpoint + metadata — non-OpenAI, lobes-native |
 | `/health` | GET | gateway | liveness |
 
+**Unlisted POST paths pass through.** The POST router is path-agnostic: it
+resolves the model from the request body and forwards the *original* path to
+that model's owning lane. So a vLLM-native route the table above does not
+list — `/tokenize` is the one seen in practice — reaches the backend and works,
+rather than 404ing. It is a passthrough, not a contract: nothing here promises
+it, the fleet's non-vLLM lanes need not serve it, and it is subject to the same
+inbound bearer gate as everything else (which is how issue #228's 1190
+unauthenticated `POST /tokenize` rejections came about).
+
 Embeddings, rerank, score, and audio (including the `/v1/realtime` WebSocket
 session) require the **fleet overlay** — they are not available when running
 the raw vLLM container in single-model mode. The generate endpoints
@@ -146,6 +155,31 @@ tool-parser plugin this pairs with.
 `"stream": true` requests are relayed chunk-by-chunk with per-chunk flushing.
 Normal (non-streaming) responses are buffered with `Content-Length`.
 
+**A streamed response always ends (issue #220).** Once the relay has started,
+exactly one of three things happens, and the client can tell them apart:
+
+| What happened | What the client receives |
+|---|---|
+| the backend finished | its own bytes (ending `data: [DONE]`), then the zero-length chunk that closes chunked framing |
+| the backend died mid-stream | an SSE **error event** (`{"error": {"type": "upstream_error", …}}`), then `data: [DONE]`, then the terminator — and the connection is closed rather than kept alive |
+| the client hung up | nothing (there is nowhere to write); the gateway logs the upstream status and attempt chain, and stops draining the backend |
+
+Both frames are sent on the failure path deliberately: a caller that parses
+error events learns *why*, and a caller that only watches for the `[DONE]`
+sentinel still terminates.
+
+Before #220 the failure paths sent **neither** — an exception unwound out of
+the relay having written no terminal frame at all, leaving the client blocked
+on a still-ESTABLISHED socket with no way to distinguish a dead upstream from
+a slow one. Measured on the DGX Spark 2026-08-27/28: 5 of 15 streamed runs sat
+17–24 minutes against a vLLM reporting `num_requests_running 0` and a GPU at
+3–7 %, until cut by hand. A client-side stream-lifetime timeout is still worth
+having (it bounds far more than this one failure), but it is no longer the
+only thing that ends a dead stream.
+
+The error event is generated by the gateway, and is never the upstream's own
+error payload — by the time it fires the upstream has stopped producing bytes.
+
 ### Audio fan-out
 
 `/v1/audio/*` requests are forwarded by the gateway to the **realtime bridge**