Skip to content
SHC Docs

Flow: the launcher

Layer 10. Edge. Edge

The apps menu injected into pages across the estate: how it establishes identity on a host that has no SHC session, why it is built the way it is, and what it cannot do.

Source of truth:

  • traefik/plugin/launcher.go: the three endpoints, the silent OIDC check, the handle store.
  • traefik/plugin/menu.go: the injected payload, the credential reader, the rendered menu.
  • ce/modules/auth/launcher.go: the mode axis, the middleware config, the injected <script>.
  • ce/modules/app/inject_traefik.go: which routers the middleware is chained onto.

Related: authentication is the estate-wide picture: every way identity is established and what is armed. This page is one subsystem in depth.

§1-§11 describe what ships. §12 is the design record for the inventory redesign (one entry per app rather than per host, an environment filter, icons on the tiles) and everything in it is either a measurement or marked PROPOSED. §13 lists what the owner still has to rule on. §14 describes the trigger’s position, which ships.

Section numbers are an interface. ce cites this document by number (launcher.md §8, three call sites in modules/auth/ and modules/app/), so sections are APPENDED and never renumbered. That is why the trigger’s position is §14 rather than the §12 its own lane wrote it as: §12 and §13 were already claimed by the inventory record, whose fifteen internal §12.x back-references would otherwise all have had to move. The lane’s code comments were updated to match, not the other way round.


The menu was unreachable on exactly the apps it was wanted on.

Its original identity check proved callers from shc_access_token, which the forward-auth gate mints, and only on the gated leg. Every app carrying its own native SSO (GitLab, Nextcloud, AFFiNE, Huly, Frappe) is deliberately ungated, because gating an app that runs its own OIDC puts the app’s callback behind the gate and breaks its login. So on precisely the apps a user spends their day in, that cookie never existed.

Measured on bitspur 2026-08-09: data-shc-launcher present and shc-apps-menu absent on every ungated app on the estate.

The ruling that followed: the launcher must authenticate the user itself, against the estate’s Keycloak, independently of the route gate.


2. The central decision: same origin, everywhere

Section titled “2. The central decision: same origin, everywhere”

/.shc/launcher/ is a reserved namespace on every hostname the proxy serves. The Traefik plugin intercepts that prefix before the request reaches the backend; nothing under it is ever proxied to the app. /.shc/ is not a path any application ships, so no app route can be shadowed by accident (launcher.go:120-125).

The callback URL is built from the current request host:

func (i *menuInjector) launcherCallbackURL(r *http.Request) string {
return gateRequestProto(r) + "://" + gateRequestHost(r) + launcherCallbackPath
}

Everything therefore stays same-origin with the page: the inventory XHR, the cookies, the postMessage target. That single choice buys four security properties for free, each of which would otherwise be a configuration to build and get right:

PropertyHow it comes free
No CORS surfaceThe inventory XHR is same-origin, so the endpoint refuses cross-origin reads outright: no allow-list to maintain. serveLauncherApps sets no Access-Control-Allow-Origin, ever.
Tenant bindingThe tenant is derived from the request host, because the endpoint is on that host. No untrusted caller-supplied origin to validate.
State bindingThe signed state names the callback URL it was minted for, so a state minted on one host of the estate cannot complete on another (launcher.go:543-548, re-checked at the callback).
Host-only cookiesNo Domain attribute anywhere. Nothing becomes ambient across the estate.

The price is that the callback URI is now per-host and cannot be enumerated in advance, which is the origin of redirectUris: ["*"] on the shc-forward-auth client. See §9.


All under /.shc/launcher/, all served by the plugin, all 404 for any other path in the namespace and 405 for anything but GET/HEAD.

PathRole
/appsThe inventory. The only place an app list ever leaves the proxy.
/startBegins the silent check. Loaded in a hidden frame; answers a 302 to Keycloak.
/callbackThe silent check’s return. Redeems the code server-side and mints the handle.
/shell/<hash>.(js|css)The launcher-shell bundle. Static, content-addressed, no identity required; the names ride only the authenticated /apps response.
/icon/<sha256>.(svg|png)?k=<key>A tile’s picture. Content-addressed, cached public, max-age=31536000, immutable with the hash as ETag; answers only with the key /apps hands out. §12.8.1.
/layoutRetired (FZ-8531). GET/HEAD answer 404; all other methods answer 405. Stored arrangements remain readable through /apps. §25.

Since 2026-08-13 the owner has approved THREE widenings of this set:

  • the static prefix /.shc/launcher/shell/* (2026-08-13), which serves the daemon-materialised launcher-shell bundle. §18 carries the ruling and the file contract, §19 the plugin’s serving and loader half.
  • /.shc/launcher/layout (2026-08-16), the cross-origin launcher layout, and the FIRST endpoint in this namespace that changes anything. §25 carries the ruling, the CSRF ladder that answers the objection the old design was refused on, and the merge rule.
  • the static prefix /.shc/launcher/icon/* (2026-10-18, SHC-3519), which serves the tiles’ pictures so /apps carries names instead of data: URIs. §12.8.1 carries the contract.

The layout widening is retired. Every path in the namespace answers 405 to anything but GET/HEAD, including /layout. Widening the set again remains an owner decision.


Four independent sessions are in play, and confusing them is the usual source of error. Only two of the four belong to SHC.

SessionOwnerHostMeaning
Keycloak SSOKeycloakauth.corp.<estate>The only one that means “who you are”.
App sessionthe appthe app’s hostOpaque to everyone but the app.
shc_access_tokenforward-auth gatethe app’s host, Path=/, LaxGated routes only.
shc_launcherthe launcherthe app’s host, Path=/.shc/launcher/, None, 30 minAn opaque handle, not a token.

Plus two short-lived CSRF cookies (shc_oidc_state (gate) and shc_launcher_state (launcher, Path=/.shc/launcher/, 5 min)) and shc_id_token on the gate’s logout path.

One more, and it is the only cookie here a script is meant to read: shc_launcher_open (Path=/, Lax, Secure, not HttpOnly, 60 s). The callback sets it when the signed state says a press began the round trip, and the payload reads it and deletes it in the same breath. It carries no identity and authorises nothing; its whole content is 1, and its whole job is “open the menu once, for the press that asked”. See §24.

SameSite=None on the launcher’s cookies is required, not a weakening: the callback can be reached by a cross-site redirect landing inside a frame, which is always the case when the app host and the auth host sit on different registrable domains (§8). The cookies are HttpOnly, Secure, path-scoped to the plugin’s own prefix, and the state cookie’s entire authority is “a callback may complete”.

shc_launcher is a handle, not a credential. The access token is held in memory inside the middleware, keyed by a random handle; the browser only ever receives the handle, HttpOnly. It buys one endpoint and nothing else, and no script can read it.


On an ungated app the inventory XHR returns 401, and the reason people get stuck here is that “not authenticated” is true in one sense and false in the other:

  • Not authenticated to SHC. No Authorization, no shc_access_token (never minted; the route is ungated), no shc_launcher yet. That is what the 401 reports, and it is correct.
  • Authenticated to Keycloak. The user logged in at auth.corp.<estate> moments ago to get into the app. That cookie exists. SHC simply cannot see it, because it is on another host.

The 401 is therefore not a dead end. It is the trigger for converting the second fact into the first.

The app’s own cookie is no help, and the reason is worth stating precisely: it is delivered to /.shc/launcher/apps (same host, Path=/) and the plugin can read the bytes. It is an opaque identifier that only resolves inside the app’s own session store. Not signed, no claims, unverifiable by anyone else. So the plugin does not even look at it: menuCredentialOf reads exactly the Authorization header and the shc_access_token cookie (menu.go:485-495). Everything else on the request is ignored, not rejected.

This is not an SHC limitation. It is how OIDC works. Apps never share sessions; each independently obtains its own proof from the IdP. The launcher is one more party doing exactly that.


Fresh browser, ungated app with native SSO (GitLab on bitspur), launcher mode auto.

Phase 1: the app logs you in. SHC is not involved.

  1. GET git.corp.bitspur.com/. Traefik proxies; there is no gate. GitLab serves its login page. The plugin injects its script into that HTML; the visitor is anonymous, so what the script renders is the sign-in offer, a trigger, never a menu (§6, prompt=none).
  2. GitLab’s own auto-redirect fires and sends the browser to Keycloak with GitLab’s client_id.
  3. The user authenticates at auth.corp.bitspur.com. Keycloak sets its own session cookie on its own host. This is the cookie everything downstream depends on.
  4. Keycloak returns a code to GitLab’s callback. GitLab redeems it with its own secret and sets its own session cookie.
  5. The dashboard renders; the plugin injects the launcher script into it.

Two cookies now exist on two hosts. Neither belongs to SHC.

Phase 2: the launcher obtains its own identity.

  1. The script XHRs /.shc/launcher/apps. No credential the plugin can read → 401, empty body.
  2. That 401 triggers probe(), which creates a 1×1 hidden iframe parked at left:-10000px, pointed at /.shc/launcher/start.
  3. /start asks the daemon for this host’s realm and client, mints a signed state bound to this host’s callback, sets shc_launcher_state, and 302s the frame to Keycloak with client_id=shc-forward-auth, scope=openid, and prompt=none.
  4. The frame navigates to auth.corp.bitspur.com, so the browser attaches the cookie from step 3. Keycloak recognises the session and, forbidden from rendering UI, answers 302 with a code.
  5. The frame lands on /.shc/launcher/callback. The plugin checks the state cookie against the state parameter, verifies its HMAC, and confirms the state was minted for this host. It then POSTs the code plus the confidential client secret to Keycloak’s token endpoint, server to server.
  6. Keycloak returns an access token over that back channel. The plugin stores it in memory under a random handle and sets shc_launcher=<handle>. The callback page postMessages ok to the parent; the parent verifies both e.origin and e.source and drops the frame.

Phase 3: the inventory.

  1. The script re-runs the same XHR. It now carries shc_launcher, which the plugin resolves back to the token.
  2. The plugin proves the identity with the daemon (§7), intersects the verdict with this tenant’s routed hosts, and answers with Cache-Control: private, no-store and Vary: Cookie, Authorization.
  3. The script builds the menu into a shadow DOM inside a fixed div pinned to all four viewport edges with pointer-events: none.

A tile is a square carrying one picture and no visible text. Its accessible name is not visible text either way: aria-label and title on the anchor both carry <app>: <verb>, and the <svg> is aria-hidden="true" focusable="false", so exactly one name is announced per tile whether or not any art resolved.

The art is an inline SVG built with createElementNS, and that is the whole reason it is free. An <img>, a background-image or a CSS mask are all fetches, which img-src governs; cooperating with img-src would mean a third editor in csp.go and a new claim on somebody else’s policy. Elements are markup, not fetches, so no CSP directive applies to them at all, exactly as the SHC mark is three positioned spans rather than a data: URI. Measured against SonarQube’s real policy and against a deliberately image-hostile one (img-src 'none'): the launcher renders and img-src, style-src, font-src and media-src come out byte-identical.

The geometry rides the /apps response, in a glyphs map deduplicated to one path per distinct category present, with a short i key per tile. It does not get a fourth endpoint: the three endpoints in §3 are a security-relevant constant, and 1,929 bytes of sheet on a 3,151-byte response (measured: 16 tiles spanning 14 categories) is cheaper than a new path in the reserved namespace plus a second round trip and its failure mode. It costs the injected payload (the byte-ceilinged artifact that lands on other people’s pages) 284 bytes, because the name and hostname lines it replaces were larger than the renderer that replaced them.

The glyphs are keyed by the catalogue’s own category:, through an app-name table in traefik/plugin/icons.go that mirrors every packaged app. 81 of the 91 packaged apps (89.0%) resolve to art; the rest, and every deployment installed after the image was built, render a monogram: two characters of the label in a hue derived from it. That is the common path, not an error path: the table is baked into an image and the catalogue grows on its own clock.

The catalogue’s own icon: field is deliberately unused. 76 of 91 apps carry one, and every value is an absolute third-party HTTPS URL across 57 distinct origins. Rendering them would owe an img-src concession naming 57 foreign hosts on every app the launcher rides on, and would beacon every user’s browser to 57 vendor CDNs from a page belonging to somebody else’s organisation. Vendor logos are a separate question (a trademark one), and the table is app-name keyed so that ruling lands as data, not code.

The one-line version: the app’s login and the launcher’s login are two independent OIDC flows against the same Keycloak, using different clients and different redirect URIs, run minutes apart. The only thing they share is the Keycloak session cookie from step 3, and the second is silent purely because the first already created it.

A fetch() to Keycloak’s authorize endpoint cannot do this. It is cross-origin: CORS blocks reading the response, Keycloak sends no Access-Control-Allow-Origin, and a fetch cannot usefully complete a redirect chain that lands back on the original origin and sets a cookie there.

An iframe navigates like a tab. It follows 302s across origins, the browser attaches each host’s cookies as it goes, and it ends up back on the parent’s own origin, where it is finally same-origin and can postMessage. It is the only browser primitive that makes that round trip invisibly.

Two things, and both are load-bearing.

It can never log anyone in. Keycloak answers from the existing session or returns login_required. Nothing is signed in silently, no login form is ever rendered, and no prompt interrupts anybody, which is what makes this safe to run on a page belonging to someone else.

login_required is not a dead end, and since 2026-08-11 it is not a silence either. On that answer the payload renders its sign-in offer: one floating 52px trigger, no dialog, no inventory, no navigation until it is pressed. That is also what a local app password login now produces. It creates the app’s session without ever creating Keycloak’s, so the probe answers login_required and the user is offered the SSO login the menu actually needs, where before they got no menu and no explanation.

Expired and anonymous are the same answer, deliberately. Nothing the browser can see distinguishes “the SSO session died under me” from “I have never signed in here”: /apps and /start refuse identically in every failure case on purpose (§7), and a payload that could tell the two apart would be a disclosure channel rather than a feature. So the offer renders for both, and a genuinely anonymous visitor to a launcher-enabled page sees the trigger too. Two things bound that cost:

  • the trigger does nothing until pressed. No dialog is thrown at a stranger, no app is named, and the one location.assign in the payload is reachable from the press handler alone.
  • the page had to opt in. Inject() refuses any body that does not already carry data-shc-launcher, and under the shipped default (launcher: button, §8) an ungated app gets no injected script at all. A public marketing page only reaches this at all on an estate whose operator set launcher: auto.

The alternative was the defect this replaced: the SSO session dies while an app’s own session lives on, so the app keeps serving a signed-in page and the launcher vanishes off it. Same silence, no way for the user to act on it.

Ungating the offer on “not-ok” widened it past the three answers Keycloak can give onto two states that are not answers at all. They go in opposite directions, both deliberately, and both are pinned by name in tests/unit/traefik/crosssite_test.go.

No verdict at all renders the offer. The frame is blocked by a privacy mode or an extension, Keycloak is slow, the network is gone: the probe’s timeout, f.onerror or its addEventListener catch fires and the payload learns nothing. It offers anyway, because every leg the button drives survives a dead frame; the click-through is a top-level navigation that needs no frame, and the forced-silent retry that precedes it rescues the merely-slow case with no navigation at all. Treating silence as failure would hide the launcher from precisely the browsers whose only working path is the button.

An unavailable verdict renders nothing. launcherFailed answers an ok=0 page too (for an unconfigured OIDC block on the router, an unreachable daemon, a state it could not sign) and its bytes are identical to login_required’s by design, because one shape per outcome is what keeps the callback page’s CSP hash constant. In those states the offer would be a dead button: pressing it runs /start?silent=1 (503, ok=0), then the top-level /start?return=<path>, which the same broken handler answers with a redirect straight back to the page the press came from. A full reload that lands where it started, with the button still there, grown on every launcher-carrying page in the estate at once during a daemon outage.

So the verdict page carries a third flag, data-shc-un, and the payload suppresses the offer on it. It is derived from the HTTP status in launcherAnswer: every 200 is an answer about the caller (proven, login_required, cross-site) and every non-200 is this proxy saying it could not begin a sign-in at all. That is not a hole in §7’s refuse-identically rule and not a disclosure channel; un reports the proxy’s own health, which the status line already states in the clear, and every verdict about a caller is still a 200 that the payload cannot tell apart from any other.

No Keycloak document is ever rendered in the frame. The authorize endpoint answers with a 302, not a page. X-Frame-Options governs documents rendered in frames, so it never applies. Any design that renders a Keycloak page in a frame would have to relax frame-ancestors on the origin that serves the login form.


serveLauncherApps refuses identically in every failure case: 401, no body, no hostname, no hint of which rung failed. A caller learning “you are cross-tenant” rather than “you are nobody” would itself be a disclosure.

  1. Resolve the tenant from the request host. Unrouted host → 401 before any daemon call.
  2. Read the credential: Authorization, then shc_access_token. If both are absent, resolve shc_launcher to its stored token.
  3. Prove the identity with the daemon. A proven identity whose tenant differs from the host’s tenant → 401.
  4. The entitled-elsewhere rung. If direct proof misses, fall through to /api/user/effective-apps.

Rung 4 exists because of a measured defect worth recording. /api/auth/forward-auth is the gate’s per-deployment authorization endpoint; it ends in 403 missing_role for any caller lacking stack:<this host's app>:use. Using it as the launcher’s proof asked “may you open the app you are already looking at?” rather than “who are you?”, and rendered nothing on a 403.

Measured on both estates 2026-08-09: 43 users in bitspur’s corp realm, of whom exactly one held any stack role at all, and that role was on the one app that was down. The launcher was invisible to 43 of 43 real users on every host, while the payload, the silent check, the handle mint and the CSP hash were all provably correct. Five rounds of marker-counting passed against a feature nobody could see.

/api/user/effective-apps never 403s. It is self-scoping, and a caller entitled to nothing gets 200 and an empty list. A 200 is therefore proof of a credential the daemon accepted, which is exactly what an app switcher needs. Nothing is widened: the rendered list is still the verdict intersected with this tenant’s routed hosts. What changed is the host a caller may see their list from.

7.1 There is exactly one rung that answers a list, and it is the filtered one

Section titled “7.1 There is exactly one rung that answers a list, and it is the filtered one”

Owner’s ruling, 2026-08-16: the degraded rung is deleted.

resolve used to have two rungs: the permission-filtered list, and, for a proven caller whose verdict the daemon could not supply, the whole tenant’s routed apps. The fallback was wider than the rung it backed, which is a fallback that falls open.

Measured on bitspur’s own apps.json, replayed through the real endpoint (traefik/plugin/testdata/estate_bitspur_apps.json, and launcher_disclosure_test.go re-derives both numbers on every run):

31 stacks in apps.json (39 routed-host rows, one tenant)
-2 placed:false gitlab-huly, license-broker
-1 nextcloud-picker folds into nc
=28 the tenant's routed set
-4 ivatar, netbird, paperless, uptime: no grant held
=24 what the filtered rung USED to answer

★ SUPERSEDED IN PART BY THE RULING OF 2026-08-16: see §7.1.1. The arithmetic above is still exactly how the two numbers arose, and it is still why the old fallback was a disclosure. What changed is the answer: the authoritative rung now answers 28, because the owner ruled that every app the tenant runs is displayed by default and the four ungranted ones are marked, not withheld. The last line is therefore history, not behaviour. Crucially the fallback is not what widened; the top of the ladder came down to meet it, so no rung discloses more than the rung above it and the guard passes without its expectation being edited.

Which of the two a member saw was decided by daemon health at that instant, and the two hosts the owner compared were not really two hosts; they were the two rungs, selected by each host’s access:

hostaccessrung reachedtiles
mail.corpopenno gate → forward-auth 403 → the entitled-elsewhere rung, which requires a verdict24
agents.corpgatedthe gate proved the caller → resolve → cold verdict → the tenant-wide fallback28

So mail was correct at the time and agents was over-disclosing at the time, and under §7.1.1 both hosts now answer 28, identically, which is the property the owner actually asked for (“the same tile count everywhere for the same identity”). The trigger is not theoretical: the daemon answered 429 on the 2nd of 6 rapid probes on this estate, and every cold cache key was another chance to land on it.

What replaces the fallback:

  • Serve the last-good verdict when one exists, past its TTL. This is what menuClient.Verdict already did one layer down, and it is now the whole of the degradation story.
  • When no verdict has ever been obtained for that caller, render no launcher. Not a wide one.
  • A decided 401 ends last-good. A daemon answering “this credential is not one” is not a health failure, and a revoked token must stop being answered from cache. Everything else (transport, timeout, 5xx, 429) is undecided and keeps it. That is refusal.go’s DECIDED/UNDECIDABLE split applied to the cache.

This does not conflict with “tiles never hide” (§12.5). That ruling is about entitlement: an app you hold no role for still gets a tile, and tapping it routes somewhere useful. It is a decision made from a verdict. This is about daemon health (no verdict at all) and showing apps because we could not find out what you may open is not discoverability, it is a disclosure of what exists in the tenant.

The cost is bounded and worth naming: last-good covers every caller who has opened the launcher once since the process started, so “no list” is confined to a genuinely cold caller during a genuine outage, and, on an estate whose daemon has no /api/user/effective-apps at all, to every caller. An un-rolled daemon now shows no launcher where it used to show the whole tenant.

7.1.1 Everything shows: the verdict supplies the VERB, the file supplies MEMBERSHIP

Section titled “7.1.1 Everything shows: the verdict supplies the VERB, the file supplies MEMBERSHIP”

Owner’s ruling, 2026-08-16, in three parts. The third is the mechanism and all three have to hold together:

  1. “every app in the tenant by default would be displayed, unless you explicitly turn it off.”
  2. “Take that back. No. My default, just everything. Like, actually, everything, everything. That’s the default, and that’s what I want.” (Retracting his own environment scoping.)
  3. “we have a precedence order for which environment it goes to when you click on it. Right? and all the other environments. It’s one icon per stack. But all the deployments and environments will show up in the menu when you right click or long press.”

Stated as a model:

ONE TILE PER STACK not one per deployment, not one per environment
TAP / CLICK -> opens that stack in the PRECEDENCE-ORDERED environment
LONG-PRESS / -> a menu of that stack's control surfaces (Open, its vapps,
RIGHT-CLICK and one row per Management tab)
DEFAULT -> everything shows: no grant filtering, no environment
filtering. Only an explicit per-app opt-out removes a tile.

★ AMENDED 2026-08-17: CLAUSE 3 ABOVE IS SUPERSEDED IN ITS MENU HALF.

The ruling transcribed above ends “But all the deployments and environments will show up in the menu when you right click or long press”, and this document went on presenting that as law after the owner withdrew it the following day:

“in the menu with the apps or whatever we shouldn’t support listing environments in the right click. instead you should be able to switch the console to another environment. (for floating menu you don’t change and can’t change the environment as it’s already known).”

What still holds: one tile per stack, tap opens the precedence-ordered environment, everything shows by default, and the per-app opt-out. Those are untouched.

What does not: the menu does NOT list a stack’s other deployments or environments. A launcher tile is single-environment: which deployment it opens is resolved by launcher.environment_precedence and is not a per-tile choice. Crossing that axis is the CONSOLE’s business, via the environment scope in its account menu (features/console/src/springboard/AccountButton.tsx).

Enforced in all three surfaces: the plugin’s e kids went from traefik/plugin/menu_stack.go, packages/springboard-ui/src/StackMenu.tsx carries the ruling in its header and has no environments section, and dedupeMenuEnvironments drops the losing deployment outright (TestDedupeMenuEnvironmentsDropsTheLoserEntirely).

This note exists because the superseded sentence sat here as law for a day and a half while lanes read this file to build from.

Two filters were removed and one was not.

filterbeforeafter
grant (resolve)entries the verdict did not name were droppedentries the verdict does not name are kept and marked u
environment (menuEnvPolicyAdmits)auto (the shipped default) listed only the request host’s environmentauto is an alias for all; only an explicitly named environment still filters
tenante.Tenant != tenantunchanged; this is the boundary the ruling did not move

Measured on bitspur’s live apps.json (46 corp rows, 2026-08-17): the answered set goes from 24 tiles to 33, the nine additions being immich, ivatar, netbird, paperless, peertube, postiz, supabase, superset, uptime, every one of them routed for the tenant and previously invisible to its own operator. On the frozen 39-row test fixture the same change reads 24 → 28.

Why a flag and not a drop. ce’s effective-apps API omits an app the caller holds no verb on (modules/user/types.go: “a VerbNone app is ABSENT from it (R-e), not listed with verb:none”), so absence is the only signal available. resolve now reads that absence as a fact about the tile: menuTile.unentitled → payload u → the grid paints the tile at 50% opacity. The tap still navigates, forward-auth still refuses, and the refusal is what routes the caller somewhere useful.

The precedence order was not invented for this; it already existed. menuEnvPrecedenceDefault in traefik/plugin/menu.go:

var menuEnvPrecedenceDefault = []string{
"prod", "live", "staging", "stage",
"default", "test", "qa", "dev", "development",
}

An estate overrides it with the environmentPrecedence config key at tenant or global scope, which ce resolves per tenant and stamps as envprecedence on every row of that tenant; the plugin reads it off the request host’s entry (menuEnvPrecedenceFor). Unlisted names sort after every listed one, alphabetically. It is shared verbatim with the console’s DEFAULT_ENVIRONMENT_PRECEDENCE. On bitspur today no row is stamped at either scope, so the built-in order above is what is in force.

The explicit opt-out is launcher_placed / launcherPlaced, which already existed and needed no new knob. An app declares launcher_placed: false in its app.yaml (today: gitlab-huly, a webhook with no page); an operator overrides that in both directions through the ordinary scope cascade, e.g.

Terminal window
shc config set launcherPlaced false --scope deployment -t corp -s superset -e prod

It is auditable like any other config key (shc config get), and it resolves per deployment, which answers the “whole tile or one menu entry?” question correctly and without a second mechanism: unplace the only deployment of a stack and the tile goes; unplace one environment of a three-environment stack and just that long-press entry goes, because the tile is drawn from whichever deployments remain. A stack-level switch would be unable to express the second case at all.

What “everything” does NOT mean: tenancy still bounds it. A corp identity must never see an shc, desibox or master app. The launcher resolves the tenant from the request host (menuTenantOf) and separately refuses any identity whose own tenant differs, so the boundary holds on every rung. Two named guards hold it: TestTenantIsStillTheBoundaryUnderEverythingShows and TestNoRungDisclosesBeyondTheCallersTenant; the latter asks every rung over a file that really does route a second tenant, including a rung whose daemon actively grants that foreign tenant, and names the leaked host when it fails.

Cross-tenant browsing for a platform admin is NOT implemented, and is left for a ruling. platform:manage is the only cross-class implication in the role grammar (daemon/wiring/user_role_gate.go), but the launcher never consults roles when scoping: it filters on the request host’s tenant and refuses a mismatched identity outright. So a platform admin standing on a corp host sees corp, and standing on a master host sees master only if their identity is master. The two options, with their costs:

  • Leave it (current behaviour). The launcher stays a per-tenant surface with one rule; cross-tenant browsing stays the console’s job. Cost: an operator of the whole estate cannot reach another tenant’s app from the switcher.
  • Let platform:manage span tenants. Cost: the tenant filter stops being a constant and becomes role-dependent, so every disclosure guard in the ladder needs a per-caller expectation rather than a fixed one, which is the shape of guard that has already failed this feature twice.

7.2 The verdict cache is keyed by (credential, tenant)

Section titled “7.2 The verdict cache is keyed by (credential, tenant)”

ListEffectiveApps reads ?host= for exactly one job: resolve which tenant owns that routed host, then answer that tenant’s deployments. Two routed hosts of one tenant therefore produce byte-identical answers, so the old per-host key cached the same bytes under K names: 39 rows over 31 stacks here, 4 hosts on matrix alone.

That cost twice: request rate (a caller roaming K hosts paid K identical daemon calls per TTL; 39 worst case, now 31) and divergence (each cold key was another chance to fall to the rung above). The tenant is never taken from the caller. serveLauncherApps derives it from apps.json via menuTenantOf before any daemon call.

The cache is process-wide. ce generates one shc-launcher-<project> middleware per deployment (31 on bitspur), and each calls New() and built its own client, so tenant keying alone would still have left 31 independent caches over one file and one daemon. The store is a package-level verdictStore guarded by its own lock; Traefik builds one Yaegi interpreter per plugin and calls the resolved New for each middleware definition, so package vars are per-process. Keys hash the credential and the daemon URL, so two instances collide only where they are asking the same daemon the same question for the same caller.

7.3 A grant reaches the list on the next open (FZ-8575)

Section titled “7.3 A grant reaches the list on the next open (FZ-8575)”

ce derives the list’s verbs from the token’s claims, so the list is only as new as the token behind it. Both credentials renew on the gate’s cadence (near access expiry, or halfway through the refresh window: up to about 15 minutes on Ogden), and the cache above holds an answer 30 s on top. A grant made after sign-in used to take minutes to reach the panel and the floating menu.

/apps and /panel now read the list with a token at most 5 s old:

CredentialWho renewsWhat the read skips
launcher handle (shc_launcher, app hosts the gate does not cover)the plugin, one grant per handle per 5 s, single-flight; a read that finds a grant in flight waits for itthe cached identity and verdict, when its token was renewed during this read
gate handle (shc_access_token=shcsess.…, gated hosts)forward-auth, on the /apps or /panel call itself, one grant per session per 5 s, bound to shcd before the plugin readsany cached identity or verdict older than 5 s

Neither spends a refresh token that has already expired: a session whose Keycloak idle window has closed keeps its live access token, exactly as an ordinary request would. A refused grant ends the handle or the session, as the regular renewal does. A revoke shows the same way, on the next open after 5 s. Every other caller (the layout store, page injection, a bearer) keeps the 30 s cache and the regular renewal.

The unit of the list is an APP, not a routed host

Section titled “The unit of the list is an APP, not a routed host”

apps.json is one entry per (deployment, routed host); it has to be, because it is also the authority menuTenantOf reads to answer “which tenant owns this hostname”. A deployment answering on three hostnames is three entries, and until this rule the switcher drew three tiles for one app.

dedupeMenuTiles collapses them after resolve and before the maxMenuEntries cap, so the verdict filter still sees the full host set and the cap counts apps rather than hostnames. (It used to have a second reason (the degraded rung read a per-host verb off the proof call), and that rung is gone as of §7.1.)

The key is the deployment ((tenant, environment, stack), the same key the verdict is keyed on), never the stack name. Two environments of one app are two separately reachable, separately entitled things; folding them on the stack name would silently delete one of a caller’s apps with no way to reach it. Collapsing the environment axis is the operator’s decision, below.

Which host the one tile links to, in order:

  1. A browser-facing host beats an api one, always. The app.yaml host_roles: map names the compose services a browser must not be sent to; the daemon joins it to each routed host through the host’s own service= selector and publishes the verdict as role on the file record. This rung is FIRST because everything below it is order, and order is what Terraform destroys; see the box below. The marker is optional and absent means browser-facing, so this rung is a no-op on every deployment that has not declared one, and it can only ever reorder within a deployment: an all-api deployment still gets its tile.
  2. The request’s own host, when this deployment routes it. Below the role rung deliberately: standing on the API host is exactly when the tile most needs to point somewhere readable. current does not become a lie, because it is computed over the WHOLE GROUP before the collapse (menuTile.current) rather than off the surviving host, which also closes the §12.6 case where a caller standing on the non-surviving host lost their aria-current altogether.
  3. The host the daemon marked primary: the deployment’s first declared --expose, derived from host_mapping insertion order. This is already the host /api/user/effective-apps builds its url from (modules/user/service.go appURL, frozen by RBAC §7.1.2), so the switcher’s link and the API’s link are the same link.
  4. The first entry in file order (alphabetical by host), reached only against a daemon predating the primary field, a stable link rather than a correct one, so an un-rolled estate degrades to today’s behaviour rather than to no link.

primary has to be a field because BuildAppsMenu sorts the file alphabetically and destroys declaration order on the way out.

Why primary alone is not enough: Terraform has no order

Section titled “Why primary alone is not enough: Terraform has no order”

shc_deployment.routes is a map. The provider lowers it through sortedHostInputs, which sorts the route keys, and - (0x2D) sorts before . (0x2E). So <name>-api sorts before <name> every single time: the apiserver becomes the first --expose argv, primary lands on it, and the deployment’s one tile opens raw JSON in a new tab.

Nothing warns, and the operator did not pick a wrong order. A map has none to pick. The moment an existing two-host app is brought under Terraform its tile flips.

host_roles: is declared in the catalogue rather than by the operator because which of an app’s images answers browsers is a property of the app: identical on every estate, knowable at package time. The hostname is the operator’s; the role is not. Declared today by dependency-track (dtrack-apiserver) and matrix (synapse), and guarded by tests/unit/catalog/host_roles_test.go, which fails if that corpus ever empties.

The scoped config key launcherEnvironment names the one environment a launcher lists. Same idiom as launcher / launcherGzip / ssoAutoRedirect: resolved through the five-tier cascade (deployment > stack > environment > tenant > global), re-resolved every sweep, no reinstall.

Terminal window
shc config set launcherEnvironment prod # estate-wide
shc config set launcherEnvironment staging -t corp # per tenant
shc config set launcherEnvironment all -t corp # climb back out

Unset is auto: the owner’s ruling of 2026-08-11. auto means the environment of the host the browser is standing on: a page served from a prod host lists prod, a page served from a staging host lists staging, and neither lists the other. It satisfies the requirement with nothing configured, which is what the ruling turned on.

The rejected default was “unset means show every environment”. It is the safe-looking one, and it is the one that ships the defect: an estate that never sets the key keeps the twelve-tile menu forever and the feature exists only for operators who read the release notes; the same invisible-feature failure this subsystem has already shipped once.

all (and *) is the explicit show-everything: the previous default, still reachable, and the way a lower tier climbs out from under a global pin, the cascade having no “unset me” value. default and the empty environment are the same environment; matching is case-insensitive.

The daemon decides, the proxy evaluates, and auto is why. The first cut of this feature had the daemon stamp a "hidden": true boolean on each excluded entry. auto cannot be expressed that way: whether an entry belongs in the answer depends on who is asking, and the daemon writes ONE apps.json that every viewer of every host reads. A per-entry boolean would need a different value per viewer.

So the daemon publishes the policy, not the verdict. BuildAppsMenu resolves the key once per deployment and writes it verbatim as "envfilter" on that deployment’s entries; serveLauncherApps reads the policy off the request host’s own entry and applies it when it builds visible, server-side, in the inventory, never in the injected payload, which carries no inventory at all and must not start.

Reading the policy off the request host rather than off the candidate is deliberate: “this launcher shows prod” is a statement about the launcher (the page in front of the operator), so the deployment whose page carries it decides. The other reading would let a staging deployment’s own row admit itself into a prod host’s menu.

An empty envfilter reads as all. That is what every daemon predating the field writes, so an estate mid-roll never loses tiles: the plugin and the daemon do not ship in the same artifact and never land at the same instant.

Nothing is ever dropped from the file. The entry stays authoritative for menuTenantOf, so a host filtered out of one launcher’s list keeps its tenant, keeps its injected launcher, and is shown the listed environment’s apps. Dropping the entry instead would answer that host a bare 401 and take the switcher off it entirely, an outage wearing a preference’s clothes.

An estate that filters everything out for a tenant refuses with the same bare 401 as every other rung: an empty launcher is worse than no launcher.

The environment suffix follows from this. renderMenuApps appends (<environment>) to a label only when the answered list actually spans more than one environment. Under auto (and under any named environment) it never does, so no tile carries an environment, which is the requirement (“not even environments listed”). On a mixed list the suffix is the only thing distinguishing two tiles of the same app, so it is kept.

Latency is two intervals, not one: the clusterfs licence section renders apps.json within a minute and the plugin re-reads the file on its own 30 s TTL. A shc config set launcherEnvironment therefore takes up to both before a browser sees it, declared on the key’s KeyEffect so an operator is told rather than left to guess.


The launcher axis has three values, and the shipped default is button, which chains the middleware onto gated routers only. ce/core/config/default.yaml:163 sets launcher: true, coercing to button; no catalogue app declares a launcher: field.

Only launcher: auto chains the middleware onto a deployment’s open app routes (inject_traefik.go:657-661). Under button, an ungated app gets no injected script and /.shc/launcher/* is not served at all; the request passes through to the app, which 404s it.

So on a default estate, everything in §6 is dormant on exactly the apps §1 says it was built for. Whether either estate sets auto is runtime config, not repo state.

A document may legally omit </body>, and used to lose the launcher

Section titled “A document may legally omit </body>, and used to lose the launcher”

Measured on bitspur, 2026-08-16. openreplay.corp.bitspur.com serves a 1420-byte text/html shell that ends:

</p>
</div>

No </body>. No </html>. Not malformed. HTML5 §13.1.2.4 makes both end tags OPTIONAL, and html-minifier’s removeOptionalTags takes the option. It is ordinary build output.

Both of the launcher’s injection points keyed on that tag, so both missed:

  1. ce’s generated rewrite is the literal regex </body>. ReplaceAll matched nothing, so data-shc-launcher was never planted.
  2. findBodyClose returned -1, and the menu, banner and auto injectors all read -1 as “fragment: append nothing”.

Result: no button, no menu, no /apps call, no log line. The same shape of silent absence as §1 and §7, on a third axis.

The fix is injectionPoint, which separates two questions that had been treated as one: “where is the closing body tag” and “where does content go”. When there is no tag, a body that DECLARES itself a document (a doctype or an <html> opener in its first 1024 bytes) gets content appended at its end; a body that declares nothing still gets nothing, because that is what protects htmx and turbo partials from having a launcher stapled into the middle of them. The rewrite injector gets the matching fallback for the one rule shape that names the tag.

This is NOT the case-sensitivity defect (</BODY> losing the launcher while the banner rendered), which is a different bug with a different fix. The fallback here is gated on the plugin’s full (?i)</\s*body\s*> grammar rather than on ce’s narrow literal, so it fires only when NO spelling of the tag exists; the two changes partition the problem and neither can mask the other’s regression.

What this was NOT. Three plausible causes were measured out first, and the sweep that filed this bug had the pattern backwards:

  • Not the forward-auth gate, and not middleware ordering. Six bitspur routers chain [shc-oidc@file, shc-launcher-…] in exactly that order: midpoint, openhands, openreplay, paperless, pulp, uptime. artifacts.corp.bitspur.com (pulp) is one of them and renders the launcher fine, signed in, screenshotted.
  • Not the ingress omitting the middleware. Every routed host on the estate carries its shc-launcher-<project> middleware, gated hosts included.
  • Not the SPA replacing the DOM. The payload never reached the document to be replaced.

The “gated hosts never inject” bucket was an artifact of probing / UNAUTHENTICATED: the gate answers 401 text/plain, which says nothing about the signed-in response. agents (openhands) closes its body tag normally and is not affected by this at all. picker is a third case again; it ships zero HTML files and answers every path with 401 application/json, so there is no document to decorate and its absence from the launcher is correct rather than broken.

Step 9 requires the browser to send Keycloak’s cookie to Keycloak from inside a frame on another host. Whether that is allowed turns on whether the two share a registrable domain:

  • git.corp.bitspur.com framing auth.corp.bitspur.com, both under bitspur.com, same-site, cookie flows. Works.
  • hq.flyingfoxlabs.in framing auth.corp.bitspur.com, different registrable domains, genuinely third-party. Safari has blocked third-party cookies since 2020; Firefox partitions them (a partitioned jar contains no session, because the real one was set first-party); Chrome is phasing them out.

On such a host Keycloak sees an anonymous browser and answers login_required for logged-in users too, indistinguishable, from inside the frame, from being logged out.

That silence is fixed, and it was never fixed only here. The payload renders its sign-in offer on any not-ok verdict the proxy did not mark UNAVAILABLE (§6; an outage or an unconfigured router still renders nothing, because there the button would be dead), so a cross-site host and a same-site host whose SSO session expired now behave identically: trigger, press, top-level login. What remains structural on these hosts is the silent check, not the launcher; no hidden frame will ever prove a user across registrable domains, so a cross-site host always pays the one click, while a same-site host pays it only when its SSO session is genuinely gone.

This is not an exotic edge case. The hidden-iframe silent check is a standard pattern (OIDC Core prompt=none; every OIDC SPA library’s silent renew; Keycloak’s own check-sso), and third-party cookie blocking is the reason the industry moved off it to refresh-token rotation. SHC is meeting a well-known wall, not a novel one.

Two things that sound like fixes and are not:

  • CHIPS / Partitioned gives the embed its own jar per embedding site. That jar has no Keycloak session in it. Wrong tool.
  • Related Website Sets is Chrome-only in practice, requires submission to a Google-maintained list, and caps set size, unusable where every customer brings their own domain.

The plugin acknowledges this per request: launcherSameSite (traefik/plugin/launcher.go) compares the app host’s and the auth host’s registrable domains (approximated stdlib-only (Yaegi cannot import the real publicsuffix table), with both error directions of the approximation degrading to today’s behaviour or to one extra click). On a cross-site verdict /start short-circuits to the xs verdict page without consulting Keycloak, which saves a doomed cross-origin round trip on every page view. SameSite, a different mechanism, was always handled correctly and is unchanged.

xs is now a server-side saving only. The verdict page still carries data-shc-xs, but the payload no longer reads it: the offer is what a not-ok answer renders, whatever made it not-ok. Dropping the read took 40 bytes out of the injected constant (10,210 → 10,170), the launcher’s first bugfix to make the payload smaller, and it is smaller for the same reason it is a fix. Suppressing the offer on data-shc-un (§6) put 23 of those bytes back, for a net 10,193 against an unmoved 10,250 ceiling; the two flags are not interchangeable, and the arithmetic is written out over menuPayloadByteCeiling. xs was a verdict about the caller’s topology, which the offer had no business gating on; un is the proxy’s own health, which it must. The press behaves identically wherever it renders: it first attempts document.requestStorageAccess() plus a forced-silent retry (/start?silent=1), then falls back to a top-level first-party redirect (/start?return=<path>, the path riding the signed state).

Mixed registrable domains are the norm, not the exception

Section titled “Mixed registrable domains are the norm, not the exception”

A single cluster is expected to serve hosts under several registrable domains at once. That has two consequences:

  • Cross-site is a steady state, so the silent iframe should be understood as an optimisation available when the topology permits, not as the mechanism. Same-site-ness is computable per request; the plugin knows both hosts.
  • No wildcard can span domains. Keycloak matches a bare * or a trailing wildcard on a fixed host, never a * in the host segment (ce/modules/auth/forward_auth_client.go:144-146). Between * and full enumeration there is nothing.

auth.SSOSelectorMiddleware sets appsMenu: {enabled: false} (ce/modules/auth/launcher.go:277). Frappe’s login_path now matches /, so on a Frappe deployment an authenticated visitor’s home page chains the selector middleware instead of the launcher middleware and loses the button. Known and unfixed; it is a missing button, not a broken login.


The launcher’s callback is per-host by construction, the set changes as apps are installed and removed, and the gate “must complete a login for hosts it cannot enumerate in advance”. Hence the wildcard (forward_auth_client.go:149-151).

The mitigation the design relies on is that a code redirected to an attacker origin cannot be redeemed without the secret the sidecar holds. That is true, and it is thin: there is exactly one such secret, shared estate-wide, resolved once at global scope (ce/modules/auth/types.go:113-120). The wildcard is survivable only because the secret holds, and the secret is itself an open owner decision. Either alone is defensible; together, one disclosure turns the estate into a session-theft primitive.

* also defeats cross-tenant isolation: the client exists in every tenant realm, and a wildcard in tenant A’s realm will accept a redirect to tenant B’s hostname.

The narrow forms are unavailable (no host-segment wildcards), so the only alternative is enumeration, and the machinery already exists: forwardAuthRedirectUrisJSON(extra []string) appends caller-supplied URIs additively, with * merely hardcoded first. SHC already knows every routed host; it writes the Traefik routers from that set.

The unsolved part is ordering: a host must exist at Keycloak before the first login through it, and route materialisation and the Keycloak reconcile run on different clocks.


Recorded so they are not re-proposed without their costs. The first two were rejected in the original design; the rest were analysed in review on 2026-08-10 and are not formal rulings.

AlternativeWhy not
Parent-domain session cookieCreates an ambient credential readable on every host of the parent domain, including hosts SHC does not control: strictly worse blast radius than host-only. And it structurally cannot cover an estate that routes a foreign domain.
Public client + PKCE in the pageThe textbook silent check hands the access token to JavaScript. One XSS in one app becomes an estate token. Rejected in favour of a server-side exchange behind an opaque handle.
Menu rendered by KeycloakKeycloak knows who you are, not the estate’s inventory, routed hosts, tenancy or entitlements; it would need a network path to the daemon it does not have today (verified: no extension in keycloak/ references any daemon endpoint or port). It also requires relaxing frame-ancestors on the login origin, and a cross-origin child cannot resize its own frame, so the panel could not expand without a parent script anyway.
Central launcher originOne handle per estate instead of one per host is a real prize. It costs the tenant binding and the CORS refusal, which are currently free, and needs an allow-list of embeddable origins, and it makes the cross-site case worse, since the frame load, postMessage and inventory call all become cross-site too.
Icons from the catalogue’s icon: URLs76 of 91 apps carry one and all 76 are third-party HTTPS URLs across 57 origins. Costs an img-src concession naming 57 foreign hosts on every app the launcher rides on, plus a beacon from each user’s browser to each vendor CDN from a page belonging to another organisation, plus link rot as the authority on how an estate looks.
A sprite endpoint under /.shc/launcher/Widens the reserved namespace’s three endpoints (a security-relevant constant) for a document of a couple of KiB, and buys a second round trip and its own failure mode. Deduplicating the geometry onto the /apps response costs less on a fetch that already happens once per page view.
Bundled vendor logosA trademark question with an owner’s name on it, not an implementation choice. Left as a data-only seam: the glyph table is app-name keyed, so a ruling lands as entries rather than as code.
Per-domain auth hostnamesWould make everything same-site again, and is what commercial IdPs call a custom domain. Collides with Keycloak 26 hostname-v2: KC_HOSTNAME pins one frontend URL and the issuer derives from it (PublicURL() + "/realms/" + realm). A second Keycloak per domain fragments the SSO session, destroying the premise. Needs its own investigation.

Two independently shippable pieces, in dependency order.

Cross-site detection with a click-through fallback: BUILT, and since 2026-08-11 no longer only cross-site. The plugin computes same-site-ness per request and short-circuits the doomed framed leg on a cross-site host. The sign-in offer it drives renders on any not-ok verdict the proxy did not mark unavailable, and on a probe that never answered at all (§6): the press runs a top-level redirect, which is first-party, so the cookie flows on every browser with no third-party-cookie dependency, after attempting document.requestStorageAccess() plus one forced-silent retry that keeps the silence when the browser permits it. This is what makes the launcher work at all on a mixed-domain cluster, and what stops it vanishing off a same-site page whose SSO session expired under a live app session. The anti-bounce shape is guarded from both directions (tests/unit/traefik/crosssite_test.go): no navigation without a gesture, no tab-scoped store (the pair of properties whose naive fixes are each other’s defects), and both directions are now driven on the same-site verdict as well as the cross-site one.

Redirect-URI enumeration in shcd, staged so it cannot break logins: populate extra from the routed-host set additively while keeping *, and log any login whose redirect_uri is outside the enumerated set, turning “can every host be enumerated in advance?” from an assumption into a measurement. Then drop * behind a per-estate flag, then flip the default.

Both are blocked on nothing. The wildcard’s removal is only worth doing alongside a ruling on the shared client secret, since the two risks only compound together.


12. The inventory model: the unit is the app

Section titled “12. The inventory model: the unit is the app”

Design record for the inventory redesign opened 2026-08-10. Three requirements, verbatim:

  1. “use icons instead of names for the actual apps that are listed”
  2. “it shouldn’t be an app per host; it should be each one per app”
  3. “not even environments listed. So for multi environment … you’d specify in the config somewhere what environment the launcher’s gonna show. And then that’s all it shows.”

Everything below is either a MEASUREMENT of what ships today or is marked PROPOSED. Nothing here describes behaviour that has landed.

Why this is §12 and not a new §8. ce cites this document by section number in six places (modules/app/inject_traefik.go, modules/app/sso_redirect.go, modules/auth/launcher.go and three tests all say “launcher flow doc §8”), and a handoff cites §9. Renumbering would silently invalidate seven cross-repo references to sections whose content did not change, so the new material is appended.


12.1 What a record is today, at each of the three layers

Section titled “12.1 What a record is today, at each of the three layers”

The word “app” names a different thing at each layer, and the redesign turns on which one it means.

LayerRecord granularityKeySource
apps.json (the file the plugin reads)one per (deployment, routed host)tenant + environment + stack + host + pathce/modules/app/apps_menu.go, BuildAppsMenu
/api/user/effective-apps (the verdict)one per deploymenttenant + environment + stack, with hosts[] plural insidece/modules/user/service.go, ListEffectiveApps
the RBAC grantone per deployment, environment-blindtenant + stackEffectiveVerb(id, d.Tenant, d.Stack)
the rendered tileone per (deployment, routed host)the file record, one to onerenderMenuApps, traefik/plugin/menu.go

Two facts fall out of that table and they carry the whole design.

The file is the only layer that is per-host. The verdict already speaks in deployments. So “one entry per app” does not need a new question asked of the daemon; it needs the file’s rows folded back into the shape the verdict was already answering in.

Nothing anywhere is keyed on the catalogue app. There is no grant, no verdict entry and no route keyed on frappe. app is carried in the file and in the verdict as a string, and ce’s own field comment says what it is for: “the catalog app name: display metadata, may differ from Stack when the operator named the deployment” (AppsMenuEntry.App). Display metadata is a fair description. It is never read as a key by anything.


12.2 stack is the axis; the deployment is the running unit; the catalog thing is an app

Section titled “12.2 stack is the axis; the deployment is the running unit; the catalog thing is an app”

AppsMenuEntry.Stack is the stack axis: the name the operator typed, what the Docker project is composed from, and what the RBAC role stack:<name>:use names. It is unique per tenant and environment:

index.Fields("tenant_name", "name", "environment").Unique()

(ce/ent/schema/deployment.go:224.) App is the app the deployment was installed from. One app can back any number of deployments; a deployment has exactly one app.

Reading requirement 2 as “one entry per catalogue app” and reading it as “one entry per deployment” therefore produce the same list on an estate that installs each app once, and different lists on an estate that does not. This estate does not.


12.3 ★ Three frappe benches: where the two readings disagree

Section titled “12.3 ★ Three frappe benches: where the two readings disagree”

The bitspur estate runs the frappe catalogue app three times, and the divergence is recorded in the app’s own measurements (apps/devops/frappe/app.yaml, measured 2026-08-05 and 2026-08-10):

Deployment hostWebsite Settings.home_pagedisable_user_pass_login
hq.corp.bitspur.comunset; / is the login page1: no password form
erp.corp.bitspur.comunset; / is the login page0: password form present
hq.flyingfoxlabs.in"home"; / is a public marketing page1: no password form

Same image, same app.yaml, three different sites. The restore inventory measured different installed application sets on two of them (scrum and frappe_keycloak on one, india_compliance on another, apps/flagship/frappe/addons/), which is to say three different companies’ books. And hq.flyingfoxlabs.in is a different organisation’s own hostname, which the plugin’s payload work already treats as a disclosure boundary: shipping that hostname inside the injected script on another customer’s site is the leak menuPayloadByteCeiling exists to bound (§12.8).

Collapsing those three to one tile labelled “Frappe” would ask the renderer to pick one of three links. Every choice is wrong for somebody, and one of them is wrong across an organisation boundary.


PROPOSED. The tile’s identity is (tenant, environment, stack), the deployment. Routed hosts of one deployment collapse into that one tile. Deployments never collapse into each other, whatever catalogue app they came from.

That is exactly the duplication requirement 2 names: “it shouldn’t be an app per host”. A deployment answering on mail.example.com and autodiscover.example.com produces one tile instead of two. Multi-host deployments are first-class and operator-made; --expose is a StringSliceVar (ce/modules/app/commands/install.go:153), so a deployment carries as many host mappings as the operator declared, and the plugin already records the two-host case as a live defect source: the reason the verdict’s current flag is deliberately not read is that “a stack answering on two hosts would … stamp aria-current on two tiles” (traefik/plugin/menu.go:434).

The decisive argument against per-catalogue-app is not aesthetic. It is that the entitlement model has no per-app key to collapse onto. The verb painted on a tile comes from verbs[verdictKey(e.Tenant, e.Environment, e.Stack)] (traefik/plugin/menu.go:1019), and the grant behind it is EffectiveVerb(id, tenant, stack). A user may hold stack:erp:use and not stack:hq:use. There is no verb that describes “frappe”, so a per-app tile either paints a verb it did not earn, paints none, or paints the maximum across the group, and the third turns a display change into an authorization claim.

It gets sharper. On the filtered rung resolve drops an entry the verdict does not name. A per-app group survives if any member is named, so grouping frappe’s three deployments and entitling the caller to erp alone keeps the group alive and hands it a representative link that may point at hq, an app the caller was never entitled to and, before the grouping, was never told existed. Per-app dedupe converts “absent” into “named, and refused on arrival”. Per-deployment dedupe cannot: every host inside one group shares one verdict key, so the group is entitled or absent as a unit.

Rejected, with its cost recorded: if the owner does want one icon per catalogue app, the honest form is a grouped tile: one icon that expands to its deployments when a tenant has more than one. That is a UI change inside the panel rather than a change to the inventory, and it keeps the per-deployment link and the per-deployment verb intact. It costs payload bytes (§12.8) and it is not what the siblings built.


Section titled “12.5 What a tile links to when reachability and entitlement differ”

Rung 4 exists because those are different facts (§7), so the redesign has to say what a tile does when they diverge. Today’s answer is measured, not designed, and it is already the right one.

On the filtered rung there is no tile. resolve looks each visible entry up in the verdict and drops the ones it does not name (traefik/plugin/menu.go:1021). A caller standing on an app they hold no verb on gets a panel that does not contain the app they are looking at: no tile, no aria-current, nothing to link anywhere. Rung 4 changed which host a caller may see their list from; it did not add the current app to the list. Preserve that: the list is what you may open, and you may not open this one.

On the degraded rung a tile can exist without a verb. SUPERSEDED 2026-08-16: there is no degraded rung. This paragraph used to describe a caller who was proven but whose verdict was unavailable being rendered the whole tenant’s routed apps with an empty verb. That rung is deleted (§7.1): an unavailable verdict now serves the caller’s last-good list, or no launcher at all if they have never had one. A verb-less tile can no longer arise from daemon health, only from the entitlement question below, which is a decision made from a verdict.

The proposal that rode on it is void with it. It read: add no wire state, because the absence of v already means “entitlement unknown” and the response already carries state: degraded. state can now only be filtered (menuStateFiltered is the only value that survives), so there is nothing to key reduced emphasis off. Any future “entitlement unknown” affordance has to be re-derived from the entitlement rungs below, not from a health signal that no longer exists.

What must not happen is the per-app group of §12.4, because it produces the one genuinely wrong case: a tile present because a sibling deployment was entitled, linking to a deployment the caller holds nothing on. Absent is a correct answer. “Present, and refused on arrival at a deployment you were never told about” is not.


Section titled “12.6 How a multi-host deployment resolves to one link”

PROPOSED, and it needs a stated rule, because two already exist and they disagree.

  • The daemon’s rule. EffectiveApp.URL is "https://" + firstHost(d.Hosts) + normaliseAppPath(d.Path) (ce/modules/user/service.go:719), and d.Hosts arrives in host_mapping.id order, insertion order, the order the operator declared them in.
  • The file’s rule. BuildAppsMenu sorts entries by (tenant, environment, stack, host, path) (host ascending, alphabetical) and the plugin preserves file order, so “the first entry for this deployment” is the alphabetically first host.

For a deployment installed as --expose mail.example.com --expose autodiscover.example.com those two rules name different hosts. A dedupe that keeps “the first row” would link somewhere the daemon’s own url field does not.

The recommendation is to keep the file’s rule and say so: the surviving host is the first in the file’s existing sort, which is the lowest hostname. Reasons, in order:

  1. The plugin cannot see insertion order. The file does not carry it, and adding an ordinal is a file-shape change for a tie-break.
  2. The file’s order is already deterministic and already content-idempotent, the property WriteAppsMenuFile depends on to avoid re-inoding the file every sweep. Reusing it costs nothing.
  3. It is stable under reinstall. Insertion order is not: re-declaring the same hosts in a different order moves the daemon’s url, and would move the tile’s link with it.

The divergence is left standing rather than papered over, and it is worth an owner ruling (§13): the launcher’s link and the API’s url for one deployment can name different hosts, and nothing today says which is canonical. The narrow fix is a primary boolean on the file record (additive, so no version bump (§12.10)) written from the same Hosts[0] the daemon already uses for url. That is the only form under which the two surfaces agree by construction.

The current-tile marker is unaffected in the good case and improves in the bad one. Current is t.entry.Host == currentHost, so a caller standing on the non-surviving host of a collapsed deployment would lose their aria-current. PROPOSED: compute Current as “the request host is any host of this deployment”, evaluated before the collapse. That preserves the invariant TestMenuPayloadMarksExactlyOneCurrentTile pins (one tile, because there is now one tile per deployment) and closes the case §12.4 quotes, where two hosts of one stack both claimed it.


12.7 The environment filter, and where it is applied

Section titled “12.7 The environment filter, and where it is applied”

SHIPPED, and this section’s recommendation was RULED (2026-08-11). auto is the default. One thing changed on the way in, and it is a consequence of the ruling rather than a revision of it: the proposal assumed the DAEMON would resolve the filter and write a per-entry verdict. auto cannot be written that way. The answer depends on the request host and one apps.json serves every host, so the daemon publishes the resolved POLICY (envfilter) and serveLauncherApps evaluates it. Everything below about WHERE the filter runs is unchanged and is why it runs there.

Where. Server-side, inside serveLauncherApps, in the same loop that already narrows entries to the request host’s tenant:

for _, e := range entries {
if e.Tenant == tenant { // ships today
visible = append(visible, e)
}
}

The environment predicate joins that condition. It must sit there and nowhere later, for the reason §7 gives about the endpoint as a whole: /apps is the only place an app list leaves the proxy, so a filter applied in the payload script is a filter applied after the list has already left. A client-side environment filter would ship every environment’s hostnames to the browser and hide them with CSS, the exact class of defect the payload’s “IT CARRIES NO INVENTORY” rule exists to prevent.

The refusal shape does not change. An empty visible already ends in launcherDeny(w) (a bare 401), so a filter that matches nothing refuses byte-identically to a stranger, which is the §7 property.

What decides the value. The appsMenu block of the launcher middleware is rendered per deployment (shc-launcher-<project>, ce/modules/auth/launcher.go), so a new key rides the existing scoped config cascade exactly as launcher does: deployment > stack > environment > tenant > global. launcherEnvironment is the natural spelling: one key with a three-value grammar, the way launcher is a three-value mode rather than a bool plus a sibling, for the reason already recorded there (“two keys can resolve at two DIFFERENT scopes and compose a posture nobody authored at any single scope”).

The default is auto (ruled), and the argument that won is this. The request host already resolves to exactly one file entry, and menuTenantOf walks the entry set to read that entry’s tenant. The same walk reads its environment, at no extra cost and with no extra configuration. So:

ValueMeaning
auto (default)show the environment of the host you are standing on
<name>show only that environment, on every host
alltoday’s behaviour: every environment, labelled

auto satisfies requirement 3 on a default estate with nothing set: a user on a prod host sees prod, a user on a staging host sees staging, and no list mixes them. That matters more than it sounds, because of §8; a redesign that only works once an operator sets two config keys is a redesign most estates never see.

The label parenthetical goes away with it. Today renderMenuApps appends " (" + environment + ")" whenever the environment is neither empty nor default (traefik/plugin/menu.go:1083-1086). Under any filter but all the list is single-environment, so the suffix names something every tile shares. Requirement 3 (“not even environments listed”) is met by deleting that branch, not by hiding it. Under all it must stay: a mixed list with no environment on the tiles is a list where two tiles have the same name.


PROPOSED, and constrained by two measurements.

Today a tile is: the label in bold, the host and path beneath it in grey, an uppercase verb pill when a verb is known, and aria-current on the host match (traefik/plugin/menu.go:1315-1330).

★ The icon identifies the APP. The name identifies the DEPLOYMENT. They are different fields and both are needed. Requirement 1 asks for icons “instead of names”, and on an estate where every app is installed once that reads cleanly. On this estate three tiles would carry the same frappe icon, and only the name tells hq from erp from the flyingfoxlabs bench. So the icon comes from App and the accessible name comes from Stack, and the visible name is the thing that may be demoted (to a caption under the icon, or to a tooltip), never removed. A tile whose only content is an icon has no accessible name at all, which fails the disclosure pattern the panel already implements (role="dialog", aria-label, aria-current).

The icon now HAS a wire path. AppsMenuEntry carries an icon field as of ce feat/launcher-app-icons-ce; EffectiveApp still does not. The addition is additive and carries no version bump, exactly as §12.10 requires. The full contract is §12.8.1.

★ And every icon in the catalogue is a third-party URL. Measured on shc origin/main 2026-08-10:

count
catalogue apps91
declaring icon:76
declaring a local icon0
distinct remote origins referenced57

The 15 with no icon are almost entirely things that would never carry a tile: three test fixtures, five bridge and plug packages, and seven storage or backing-service packages. The other 76 point at about.gitlab.com, upload.wikimedia.org, raw.githubusercontent.com, supabase.com and 53 more.

Rendering those as <img src> inside the panel has four consequences, and the first is the one that matters:

  1. It re-creates the disclosure the payload work removed. The injected script is a constant precisely so that it carries no inventory. A panel that fetches 57 third-party origins announces the estate’s app list to those origins, per user, with the app’s own hostname in the Referer, including on hq.flyingfoxlabs.in, where §12.3 already establishes that one customer’s estate detail on another’s page is the leak class in question. Tile images are inventory leaving the proxy by referral instead of by response body.
  2. CSP. An app serving img-src 'self' renders 76 broken images. The plugin’s CSP cooperation path merges a script hash and two frame origins today; merging 57 image origins into another app’s policy is a widening of a different order, and it would have to be computed from the inventory, which makes a security header a function of the app list.
  3. Air-gapped and offline estates render nothing.
  4. Availability. A remote logo that 404s is a broken tile no estate operator can fix.

The recommendation was that icons are proxied or embedded, never hot-linked, and THAT IS WHAT SHIPPED. The daemon fetches each icon once, server-side, normalises it and writes it beside apps.json on the license mount, the same materialised-file doctrine the menu already uses, and the same “no outbound HTTP from the plugin” rule. A tile with no icon still falls back to the category glyph or the generated monogram, which is the common case and not an error branch. Hot-linking was never on the list and is not on it now. See §12.8.1.

The byte budget, measured, because it binds the icon work:

Statepayload bytesceilingheadroom
shc main today7,1958,192997
with §11’s cross-site fallback8,2468,704458

(TestLauncherPayloadStaysCSPAndDOMSafe reports the served size; the ceiling and its rationale live in menu_test.go.) The ceiling bounds the injected script, not the JSON response, so an icon URL per app costs response bytes, which are bounded instead by maxMenuEntries = 60 and are not gated. The <img> construction, its sizing and its error fallback are script bytes, and after the cross-site fallback lands they have 458 bytes to fit in. Raising the ceiling again is permitted and is a decision that has to be written down where the constant is; the point of recording the number here is that a third raise in one month is a signal about the payload, not about the guard.


12.8.1 The icon pipeline as built: the same-origin contract

Section titled “12.8.1 The icon pipeline as built: the same-origin contract”

LANDED in ce feat/launcher-app-icons-ce (core/appicon, modules/app/launcher_icon.go, daemon/services_seams_app_icons.go). This section is the interface between the two repos; §12.8 above is the reasoning that produced it.

The shape of the answer. The browser never learns a vendor URL. Each package ships a local icon.svg / icon.png beside app.yaml. The daemon stamps icon: "icons/<sha256>.<ext>" onto the apps.json entry, named by the hash of the bytes, and materialises them at <licenseDir>/icons/ under that name. The Traefik plugin prefers that stamp, then the category glyph the daemon stamps from the package’s category:, then a monogram. /apps names each picture by content name plus a URL on the plugin’s icon door (SHC-3519); until then it carried every picture as a data: URI, 635 KB at the entry cap, uncached. No foreign img-src origin is named, no vendor CDN is told who is looking, and an air-gapped estate draws the same tiles as a connected one.

The things the plugin side codes against:

wire keyicon, on each apps.json entry, omitempty
value"icons/<sha256>.svg" or "icons/<sha256>.png", the lowercase hex sha256 of the bytes. A relative reference the plugin matches (menuIconRefRe) before joining. Never a URL, never bytes. The plugin still reads a v0.1.21 daemon’s "icons/<app>.<ext>" and names the URL by the hash of its bytes, so an estate upgraded in place keeps its pictures before the upgraded daemon’s first sweep.
bytes<licenseDir>/icons/<sha256>.<ext>, a sibling directory of apps.json, inside the same already-bind-mounted read-only licence directory. A changed icon is a new name. The daemon prunes a file once two writes in a row have not referenced it, so a plugin still holding the previous apps.json (30 s TTL) keeps finding its files.
content typesexactly two, forever: image/png and image/svg+xml
on /appseach tile’s a is the content name; arts[name] is /.shc/launcher/icon/<name>?k=<key>
the keyk = base64url(HMAC-SHA256(gate state secret, "shc-launcher-icon\0" + sha256 hex))[:16 bytes]. Only /apps hands it out, so only a caller whose inventory carries a picture can fetch it; without it, anyone holding a catalogue icon’s public bytes could ask which apps the estate runs.

How the icon door serves them, and every clause is load-bearing:

  • Match the name against ^[0-9a-f]{64}\.(svg|png)$ before joining it to the directory. No .., no extra slash, no uppercase, no third extension. launcherIconHash is the plugin’s copy of that rule.
  • Check the key first, in constant time, before touching the disk. A malformed name, a missing or wrong key, an absent file and bytes that do not hash to their name all answer the same bodyless 404, so the door cannot tell “not on this estate” from “wrong key”.
  • Re-hash the bytes and refuse a mismatch: the answer is cached for a year.
  • Decide the Content-Type from the extension, by table lookup. Never sniff. The set is closed at two, so there is no default branch.
  • Send X-Content-Type-Options: nosniff, Content-Security-Policy: default-src 'none', Cache-Control: public, max-age=31536000, immutable and ETag: "<sha256>"; answer If-None-Match with a bodyless 304.
  • Reference the bytes from <img src>, a CSS background-image, or <object>; never inline the SVG into a live DOM. An SVG in an image context cannot run script or load subresources; that is a browser guarantee and it is the strongest fence in the stack. Inlining switches it off. The sanitiser is the second fence, not the only one.
  • On a page whose own CSP constrains images, the injector appends https://<host>/.shc/launcher/icon/ to img-src (or synthesises img-src from default-src plus it). Nothing the app listed is removed, img-src 'none' is never widened, and a policy that already admits the path ('self', *, the host) is left byte-identical.

★ EMPTY MEANS “DRAW THE GLYPH, THEN THE MONOGRAM”. Not an error, not a retry, not a placeholder. The app declares no local icon:, or the file failed a cap, or the daemon predates the stamp. Category glyphs are a last resort (they collide by construction); a letter tile on a known catalogue app is a sourcing miss.

What the daemon guarantees about the bytes. Sniffed on content, not on the vendor’s Content-Type; rasters decoded and re-encoded as PNG (which is what strips EXIF, ICC, tEXt and any trailing appendix; only pixels survive); SVG rebuilt from an element and attribute allowlist with no script, no event handlers, no external references, no foreign namespaces and no DOCTYPE internal subset; capped at 256 KiB fetched, 64 KiB stored, 192 px on a side (3x DPR for a 64 px tile), and 8192 px on any declared extent so a decompression bomb is refused before it is allocated.

Where the fetch happens, and where it must never happen. The clusterfs licence section (modules/app/license_section.go), over the DEPLOYED set, not at crawl time, because a crawl walks the whole 91-app catalogue and runs at boot on every node that ships app roots, which would dial 56 vendor origins per node per restart for icons no tile will ever draw. No launcher request path ever triggers an outbound call, and rendering the menu is a map lookup and a stat.

The failure budget is stated, because it is large. Measured against the live catalogue on 2026-08-11: of 67 distinct icon URLs, 29 produced an icon (16 PNG including all six live .ico favicons, 13 SVG) and 38 were refused: 36 of them vendor 404/403, one 288 KB of HTML served under a .svg URL with a 200, one over the byte cap. Link rot is not the edge case here, it is 45.6% of the population. Every refusal emits X200980ICNFCH naming the app, the URL and the reason, and is persisted with a 24-hour retry clock in <StateHome>/appicons/ledger.json, which is deliberately outside the licence directory, because that directory is an interface and the ledger is bookkeeping. Without that persisted negative cache a 60-second sweep would beacon three dozen vendor CDNs every minute forever, which would be a worse leak than the one this design closes.

Byte cost on the payload: zero. The value is a name in the JSON response, which is bounded by maxMenuEntries and is not gated. The <img> construction is script bytes and is the plugin side’s budget to spend against menuPayloadByteCeiling.

Section titled “Byte cost on the payload: zero. The value is a name in the JSON response, which is bounded by maxMenuEntries and is not gated. The <img> construction is script bytes and is the plugin side’s budget to spend against menuPayloadByteCeiling.”

12.9 Why the dedupe cannot leak an app across tenants

Section titled “12.9 Why the dedupe cannot leak an app across tenants”

This is a security property, so the argument is stated rather than asserted.

The dedupe operates on a set that is already single-tenant, and that is a property of its input, not of its key. In serveLauncherApps the order is fixed:

  1. menuTenantOf(entries, reqHost) resolves the tenant from the file; an unrouted host resolves to "" and refuses before any daemon call.
  2. A proven identity whose tenant differs from the host’s tenant is refused outright.
  3. visible is built by exact match, e.Tenant == tenant.
  4. Only then is resolve called, and it is called with visible.

A grouping function applied to a single-tenant slice cannot emit a cross-tenant group, whatever it groups on. The property therefore survives the redesign under one condition, which is the invariant the implementation owes:

The dedupe runs downstream of the e.Tenant == tenant filter, never upstream of it, and its group key includes the tenant.

Both halves are load-bearing, for different reasons. The filter is what makes the property true today. The key is what keeps it true after the next refactor moves the grouping: a key of (app) alone, or of (environment, stack), is one edit away from being applied to entries instead of visible, and at that moment a group would span tenants and its surviving representative could carry another tenant’s hostname. This document’s own doctrine is that a guard should not depend on the order of the code preceding it.

★ The caller who makes this concrete is the platform admin. visibleDeployments returns ListAll (every tenant’s deployments) for a platform admin (ce/modules/user/service.go:593-595), so a platform admin’s verdict genuinely names every tenant on the estate, and verdictNamesTenant passes on any host they stand on. The only thing that narrows their rendered list to the host’s tenant is step 3. It is not a redundant check with the verdict as a backstop; for that one caller it is the whole boundary. Anything that reorders the pipeline so grouping precedes the tenant filter renders one tenant’s app list on another tenant’s host, to the estate’s most privileged user, silently.

Two smaller notes, both preserved by that rule:

  • The verdict cannot widen the list. resolve iterates visible and looks each entry up in the verdict, never the reverse: “an app the verdict names but the file does not route for this tenant is simply not here to answer” (menu.go:1015). Collapsing hosts within visible does not change the direction of that lookup.
  • The environment filter of §12.7 narrows only. It is applied in the same loop and can never admit an entry the tenant test rejected, because the two are a conjunction on one record.

12.10 Constraints the implementation inherits

Section titled “12.10 Constraints the implementation inherits”

No version bump on apps.json, deliberately. The file contract is explicit: new needs are met by ADDING fields, which the plugin ignores when it does not know them, “never by bumping”, because a bump dark-fails the menu on every already-deployed image until every Traefik on the estate is rolled (traefik/plugin/menu.go, the menuFile contract block). An icon field and a primary flag are both additive and both legal. Reshaping the record to nest hosts under a deployment is not. That is exactly the incompatible reshape the version guards, and it would blank the launcher estate-wide for the length of the roll.

The same rule binds the wire response: launcherAppsFormatVersion = 1, and “the script refuses any other value, so a future reshape dark-fails to ‘no menu’ on an un-rolled image”. The plugin and the payload ship in one image, so that pair moves together, but only with the image.

Yaegi. The plugin is interpreted, not compiled, so anything added to it lives inside a restricted stdlib; a sibling lane measured os/exec as unresolvable. Yaegi also honours only the legacy // +build line and ignores a lone //go:build, so a file guarded the modern way is silently included.

Any edit under traefik/plugin/ diverges the tree from the image ce pins, which the traefik-plugin-pin arch-fitness rule refuses, reddening both make lint and make test/unit, until a rebuilt image is repinned in ce. Measured, and proven by the revert of §11’s cross-site work on shc main (89a0067b4). The plugin-side and daemon-side halves of this redesign therefore have different landing costs and belong in separate commits.


12.11 Is any of this visible? Read §8 first

Section titled “12.11 Is any of this visible? Read §8 first”

On a default estate, no.

The shipped default is launcher: true (ce/core/config/default.yaml:163), which coerces to button, which chains the middleware onto gated routers only; no catalogue app declares a launcher: field. Under button an ungated app gets no injected script and /.shc/launcher/* is not served at all; the request passes through to the app, which 404s it.

So on the apps §1 says the launcher was built for (every app carrying its own native SSO, which is every app deliberately left ungated) this redesign changes the appearance of a panel that is not rendered. It is visible on gated routes, where the flow was never broken, and on launcher: auto deployments, which are runtime config that no repo state records.

This does not make the redesign wrong. It makes launcher: auto a prerequisite for observing it, and it means “we changed the launcher and nothing looked different” is the expected result on a default estate rather than evidence of a defect. Whether either estate sets auto should be measured before the work is judged; the arming decision is listed in §13.


RULED 2026-08-11. The owner answered every question in this table. The Ruling column is what shipped; the recommendation is kept beside it because two of them were overruled and the reasoning is worth reading next to the answer.

#QuestionRecommendationRuling (2026-08-11)
1An app exists only in staging while the launcher shows prod: hidden, or shown as a fallback?Hidden. “That’s all it shows” is unambiguous, and a fallback makes the list a function of what else happens to exist, so two estates with identical config show different environments. Staging hosts are also the ones carrying debug flags and seeded data, and a fallback surfaces them precisely when nobody has reviewed them. The escape is launcherEnvironment: all, or auto (§12.7), under which a user standing on the staging host sees staging.Not re-opened: the escape is all, and the shipped default auto shows a staging host its own staging apps.
2Two deployments of one catalogue app: per-app or per-deployment?Per-deployment. Entitlement has no per-app key (§12.4), this estate has three frappe benches holding three organisations’ data (§12.3), and per-app grouping resurrects entries the verdict dropped (§12.5). If the owner still wants one icon per app, take the grouped-expanding tile, not a collapse.Per-deployment, on the key (tenant, environment, stack). Confirmed: the three frappe benches must each stay reachable.
3The launcher’s link and EffectiveApp.URL can name different hosts for one deployment (§12.6). Which is canonical?Add a primary flag to the file record, written from the same Hosts[0] the daemon uses for url. Until then the launcher uses the file’s existing sort and the two can disagree.primary landed, and is not sufficient. Terraform sorts routes, so <name>-api always precedes <name>; the per-host role marker (app.yaml host_roles:) is consulted BEFORE order. §7.
4Icons: proxied through the daemon, or a generated monogram?Proxy or embed. 76 of 91 icons are third-party URLs across 57 origins (§12.8); hot-linking re-creates the payload disclosure and breaks under img-src 'self' and offline. Monograms ship with no fetch at all and are the cheaper first cut.Category glyphs + monogram fallback. NO VENDOR LOGOS: a trademark question with an owner’s name on it, not a lane’s. The launcherAppCategory seam stays app-keyed so a later ruling is a data change.
5Does the visible app name survive next to the icon?Yes, as the accessible name at minimum. Three frappe tiles share one icon and are told apart only by name (§12.8).Only where two tiles in the answered list share an icon. Not unconditional, and no ceiling raise for it: the collision is decided server-side over the whole answer, and a tile whose glyph is unique carries no caption at all.
6launcherEnvironment default: auto (the host’s own environment), or unset meaning all?auto. It satisfies requirement 3 with nothing configured, which matters because of §8.auto. Recommendation accepted. It moved the filter’s evaluation from the daemon to the proxy; a boolean cannot hold a per-viewer answer.
7Raise menuPayloadByteCeiling a third time for icon rendering?Decide after the cross-site fallback lands and the real cost is measured against its 458 remaining bytes. Do not raise it speculatively.No. The ceiling is untouched at 10,250; the payload was 10,210 when this was ruled (10,193 today; see menuPayloadByteCeiling). The caption’s 199 bytes were paid out of a 213-byte minification, not borrowed.
8Is launcher: auto set on either estate?Repo state cannot answer it (§12.11). Measure before judging the redesign.Unchanged, still a measurement owed against a live estate, not a repo question.

Q5 OVERRULED 2026-08-13: every tile always shows its stack name, iPad-style. The sparse policy the 2026-08-11 ruling shipped (“only where two tiles share a mark; monograms never captioned”) was correct about pictures and wrong about the reader. A launcher where only SOME tiles are named teaches that a name is a warning sign, and the identification question was still being asked one hover at a time on every tile the policy left bare. What replaces it: the server (captionEveryTile) middle-ellipsizes a long name to 14 runes (middle, not end, because estate stack names differ at both ends (gitlab-s3, huly-nextcloud, <name>-api)) and the payload paints a.m||a.n unconditionally, with the full name still on the tile’s title/aria-label. The payload got 5 bytes SMALLER (10,323 → 10,318; always-on needs no conditional) and the wire pays only for names long enough to shorten, so neither ceiling in Q7’s ledger moved.


The floating trigger is draggable, and where it ends up is a dock rather than a coordinate.

Eight docks: three rails, three stops, minus one. Left, centre or right, crossed with top, middle or bottom. Release snaps to the nearest, always: the rail is which third of the viewport the trigger’s centre is in, the stop is the nearest of the three. There is no magnet radius and no free placement, so a drag that ends off-screen is not representable.

Two crossings are not docks:

  • Dead centre (centre rail, middle stop) is refused outright. It parks an opaque control in the optical middle of somebody else’s content, the one position from which the trigger obscures something no matter what the page is.
  • Bottom-centre below 600px is refused, and §14.1 is why.

The centre rail was added in SHC-235, over a design that had deliberately left it out: “top-centre is the notch, the dynamic island and every app’s own header bar; bottom-centre is the home indicator, the browser’s toolbar and every mobile tab bar.” Every one of those hazards was real. Each is now answered by a mechanism rather than by omission: the safe area writes for the notch and the home indicator, the collapse for the header bar, and the width gate for the tab bar.

The encoding is additive, not visual. DX is 0=left, 1=right, 2=centre. Centre was appended rather than inserted, because renumbering to left/centre/right would silently relocate every existing user’s trigger from bottom-right to bottom-centre on their next page load, on every host. The payload carries reading order as a string ('021') where the keyboard walk needs it.

Nothing may be obscured at a centre stop. There are only two ways to honour that, and one of them is unavailable: the launcher may not write padding onto a third party’s <body>, because that mutates the layout of an application this repo does not own and cannot test; it breaks pages whose scroller is an inner element, and double-counts against apps that already reserve their own safe-area band.

So the trigger collapses. At a corner it is 52×52 floating 16px inside the safe area, a 68px band. At a centre stop it is 52×26 flush against the safe area, a 26px band, 62% less of the page’s own edge, in the shape every platform already uses there: a half-height tab rather than a floating puck. The tap target keeps its full 52px of horizontal travel; collapsing further to a hairline grabber was refused, because a 12px target on chrome injected into every page is a worse defect than the collision it dodges.

The collapse shrinks the bottom-bar collision; it cannot delete it. A bar and a control docked to the same edge at the same horizontal midpoint share a band, and no geometry available to the payload changes that. So bottom-centre is gated on viewport width: offered at 600px and above, refused below. SHC-215’s mobile bottom bar (search, video, bell, calendar, avatar) is mobile-only by its own design, so a dock that cannot exist below 600px cannot collide with a bar that does not exist above it: structurally impossible rather than merely unlikely, and without the plugin and that soft-fork patch series having to agree about a number. The alternative (reading SHC-215’s computed bar height across repos and docking above it) was refused as cross-repo coupling re-verified on every upstream bump.

Top-centre is not gated and is live at every width. A phone gets seven docks, a desktop eight. The gate is read at every decision, never cached, so a rotation into landscape past 600px makes bottom-centre reachable and a rotation back refuses it: no resize listener, no stale flag. A stored bottom-centre read on a narrow viewport fails the same legality check the snap applies and is treated as absent, landing the trigger on its default dock rather than somewhere the snap cannot reproduce.

The default dock is width-gated too (SHC-969). At 600 device px and up a first-time visitor’s trigger starts bottom-right, as it always has. Below that it starts on the right rail’s middle stop. A phone pins its primary actions to the bottom band: a bottom sheet’s footer, a dialog’s Create, a snackbar’s Undo, Material’s FAB 16px in from the same corner. Those are fixed, so no scroll moves them out from under the puck, and mpo’s filter sheet put Apply exactly there at 375px. The middle of the edge holds scrolling content instead, and it is where AssistiveTouch rests. The gate is the one leg() reads, in device pixels. A stored dock is the user’s choice and wins at every width.

Why discrete. A free position has to be persisted as pixels, and a pixel does not survive a rotation or a collapsing URL bar; yesterday’s y is off the bottom of today’s viewport or under the home indicator. A dock re-resolves at every viewport size and is two characters of storage.

Each docked side is written twice through the CSSOM: a plain gutter, then the same gutter plus env(safe-area-inset-<side>). An engine that cannot parse the second declaration discards it and keeps the first, so the fallback needs no feature test. env() is zero on a page that never opted into viewport-fit=cover, which is correct: such a page is letterboxed and its layout viewport already excludes the unsafe area.

Position persisted on the daemon, keyed by the user, until FZ-8531. It used to live in localStorage, per host, on three arguments: that per-app was the honest scope; that there was no write path to anything durable at any layer; and that a mutation under /.shc/launcher/ would mean designing CSRF for the estate’s most widely-exposed surface. The last two were answered by §21.6’s layout lane, which built exactly that write path behind a four-rung ladder. The first was overruled by the owner in the same terms he overruled tile order: pinning is per user. On reflection it was always a good argument for a per-app override and a poor one for having no estate-wide value at all; what a user wants is “my launcher lives at the top middle”, stated once, everywhere.

It rides the layout blob, and costs the daemon nothing. The dock is one more field on the arrangement the launcher already stores:

{ "v": 1, "k": "20", "d": [], "p": [["cloud", "mail"]] }

The daemon validates json.Valid and a 16 KiB cap and stores the bytes verbatim in a json.RawMessage; it has no schema for the inside of the blob and never unmarshals it. So an estate running today’s daemon serves the dock correctly the moment the new plugin ships: no ce change, no pin bump, no daemon roll for this half. A second daemon route would have been a schema, an API, an authz story and a migration for two characters; a sibling key in the request body would have been a ce change, because that struct is typed and an unknown sibling is dropped.

localStorage wins, the stored dock seeds. On load the dock is read from the stored arrangement directly, never from the merge, and is used only when this origin’s localStorage holds no dock. localStorage is still written on every move, immediately and unconditionally, and is what positions the trigger whenever it holds a dock. The daemon leg is debounced at 400ms, but app hosts get no write token since FZ-8531, so it never fires and a move stays on the host it was made on.

Two paths have no layout machinery at all and degrade to localStorage silently: the cross-site sign-in trigger (no panel, no inventory, no token) and the subscribe pane. A cookie remains strictly worse than either: host-only too, so it solves nothing, and it rides every request.

A tap is still a tap. Nothing moves until the pointer has travelled 8 CSS px (Android’s and Chrome’s own touch slop), scaled by the same legacy-viewport factor K as everything else, so a phone rendering a viewport-less page at 0.4× gets the same physical threshold. touch-action: none on the 52px trigger is the whole answer to fighting the scroll: the browser stops claiming gestures that start there, so the pointermove stream is never stolen mid-drag, while the page still scrolls from every other pixel. The drag also owns the trigger’s click, because a drag ends in a click on every browser and a launcher that opened on click alone would fling the panel open every time it was moved; the synthetic click a keyboard Enter or Space produces still passes.

The panel is unaffected, and that is worth stating because it sounds like it should not be. The dialog is full-viewport (§ the owner’s four requirements), not a popover anchored to the trigger, so there is no expansion direction to follow and no dock that can aim it at a page’s primary control. show() also hides the trigger for as long as the panel is up, so a top-right dock cannot put it over the dialog’s own close control. The recorded “panel covered Penpot’s login form” defect was the panel being stuck open (an app’s display rule beating the hidden attribute) and is answered by the shadow root and by the pane carrying its own inline display, neither of which positioning touches.

Keyboard. A drag-only control is inaccessible, so the arrow keys walk the docks whenever the trigger has focus, and they are installed before the Pointer Events check: an engine with no pointer support keeps a trigger that taps and a trigger the keyboard still moves. The accessible name never changes (it is what a screen-reader user navigates by) and nothing is written to storage until the user chooses.

The cross-site sign-in trigger shares all of it. On a host where the silent check cannot run (§8), the offer’s button is the launcher icon the user sees (same factory, same mark, same corner), so it drags on the same eight docks and reads the same stored position. A user who moves it to sign in finds the menu’s own trigger in the place they left it. What it does not share is the daemon leg: there is no inventory on that path and therefore no token, so its dock is localStorage only, exactly as every dock was before SHC-235.

The frame self-disable (W.top !== W.self) is untouched. Positioning now declares two IIFE-level slots (the dock value and the save hook that carries it between the trigger and the panel), and both sit after the guard, so a framed document returns before either initialiser runs.

The stored key is shc-dock, and it is the one tab-scoped key the payload is allowed to touch. tests/unit/traefik enforces that by NAME: the probe harness reports every key read or written and the guards refuse any key not declared with its reasoning. The rule being enforced is not “the payload may not use storage” but “nothing persisted may suppress the silent identity check”; shc-dock is read while building the menu, after an inventory has already been served, and is never consulted on the probe path. A returning suppression latch is a new key, and it fails naming itself.

Pressing a tile opens the app in a new browsing context. The page the user was standing in is never taken.

The mechanism is the anchor’s own, and that is the whole design. The tile has always been an <a> with an href; it now also carries target="_blank" and rel="noopener", and nothing intercepts the activation. The two alternatives were both rejected on defects rather than on taste:

mechanismwhy not
W.open() from a click handlerneeds preventDefault to avoid opening twice, and preventDefault kills every modifier gesture below. It is also a programmatic popup, blocked outright wherever the click is not recognised as a user gesture.
href plus a rewritten handlerthe worst of both, and more bytes than either.

Because the browser performs the activation, middle-click, ctrl/cmd-click, “open link in new tab”, drag-to-tab-bar and copy-link all keep working, and a modifier-click opens exactly one tab rather than two. That last property is invisible to a plain left click and is the one a hand test never finds, so it is a guard (TestLauncherModifierClickOpensExactlyOneTab) with a mutation proof beside it.

rel="noopener" is the security half and it is not redundant. A context opened with target="_blank" would otherwise receive a live window.opener handle back to this document. Any script in the opened page could then call opener.location = … and silently replace the page the user believes they left open: reverse tabnabbing. The launcher lists an operator’s whole estate, so both pages look trusted to the user, which makes the swap worse rather than better. Modern engines imply noopener for target="_blank" (HTML spec, ~2021), but this payload lands on whatever browser the visitor brought: Safari before 12.1, legacy Edge and every embedded webview predating the change do not imply it. Stating it costs 17 bytes. noreferrer is deliberately not added. It would also strip the Referer header, and the default referrer policy already sends origin-only cross-origin, so those bytes buy nothing the threat model asked for.

The panel closes on activation. The dialog is full-viewport (§14, and the owner’s four requirements), so a tile that opened a tab and left the dialog up would hand the user back a page covered by a menu they had already finished with, on every return to that tab, forever. Closing uses shut(), the same function Escape and the close button call, so there is one close path rather than three; the trigger comes back at whatever dock the drag left it on and nothing about positioning is touched. It is assigned as an ordinary onclick with no preventDefault, which is what keeps the single-open property: the navigation is still the browser’s. A middle-click fires auxclick rather than click, so opening a background tab correctly leaves the panel up, which is what a user opening several apps in a row wants.

The current tile is not a special case. The tile carrying aria-current="page" opens a new tab like every other one. “Always” was the requirement, and an inventory whose current entry quietly navigated in place would be the one tile that still takes the page out from under the user.

It is announced. A control that opens a new context must say so, and an icon-only tile has nowhere to say it except its accessible name, so aria-label and title both become <app>: <verb> (opens in new tab). Extending the name rather than adding a caption is deliberate: visible text is exactly what the icon redesign removed, and it costs payload bytes the ceiling no longer has (§ menuPayloadByteCeiling, 26 B of headroom).

The guards run the payload rather than reading it (launcher_newtab_node_test.go): the harness dispatches a real click, lets the payload’s handlers prevent or not, and then models what a browser does next: open a context, recording whether that context would receive an opener handle, or navigate the current document. A string match could not tell any of those apart.

16. One tile per stack name: environment precedence

Section titled “16. One tile per stack name: environment precedence”

The owner’s rule (2026-08-13), verbatim intent: “if more than one deployment is supposed to show up in the launcher it will just show the first one by order of environment precedence. environment precedence is a config that exists only on the tenant and global scope that lists the precedence of environments. by default: production, prod, default, test, dev etc. if it’s not in the list then it’s at the end by alphabetical order of the environment name.”

The environment name is prod. The shipped default ranks it first. The name production is refused at deployment input, with an error naming prod.

The mechanism is a third collapse, downstream of the other two. The envfilter (§7) decides which environments QUALIFY; dedupeMenuTiles collapses the routed hosts of one deployment; dedupeMenuEnvironments (traefik/plugin/menu.go) then collapses the qualifying deployments of one stack name (group key (tenant, stack), the tenant half being §12.9’s invariant) down to the single one the precedence order ranks first. Under the shipped envfilter default (auto) the answer is already single-environment and the collapse is a no-op; it earns its keep under all and under an un-rolled daemon’s empty policy, the two states where one stack used to draw two tiles.

The contract, shared with the console and ce. Do not let the three drift:

config keylauncher.environment_precedence, tenant and global scope only; tenant replaces global, global replaces the built-in default
default orderprod, live, staging, stage, default, test, qa, dev, development
comparatorlisted names by list position; unlisted names after every listed one, alphabetically. Exact, case-sensitive match. (The console’s resolveEnvironmentOrder folds case before matching; on daemon-written lowercase names the two readings agree byte for byte.)
wireenvprecedence on each apps.json entry, omitempty; the daemon stamps the RESOLVED list per entry, the same policy-stamping pattern as envfilter, read off the request host’s own entry for the same reason (§7)
absentthe built-in default order. An un-rolled daemon still collapses (by the order every surface ships anyway), which is the honest degradation: the collapse keeps one tile per stack name whatever the order, so nothing can vanish outright.

The comparator exists three times on purpose (the console’s resolveEnvironmentOrder (features/console/src/launcher/precedence.ts), ce’s ResolveEnvironmentPrecedence / CompareEnvironments helpers (ce/modules/app/launcher_precedence.go), and the plugin’s menuCompareEnvironments) because the plugin is interpreted by yaegi and can import neither. Keep the semantics in lockstep; the code cannot be shared.

What the collapse must never do, each pinned by a test in menu_inventory_test.go:

  • Resurrect a deployment the verdict dropped, or hide the one it kept. It runs downstream of resolve, so it picks among deployments THIS caller may open: a caller entitled to staging alone still gets staging, whatever the list prefers. The §12.5 defect (a tile present because a sibling was entitled) stays impossible.
  • Carry a verb or current across the collapse. Every group member is a DIFFERENT deployment, so the loser’s verb is an entitlement on an app the answer no longer names, and its current marks a page the surviving tile does not link to. A caller standing on a collapsed-away environment gets no current tile, the same answer the envfilter gives a host in an unlisted environment.
  • Delete the loser. Clay’s 2026-08-14 ruling put extra environments on the surviving tile’s right-click menu (k, kind e). The kid is a link to the loser’s host, not an entitlement badge.
  • Group across tenants. The group key includes the tenant, and the collapse runs downstream of the e.Tenant == tenant filter, both halves of §12.9’s invariant, restated because this is the second function the invariant now binds.

The daemon stamps envprecedence since ce 2201a88f. BuildAppsMenu (ce/modules/app/apps_menu.go) resolves launcher.environment_precedence once per tenant (tenant row > global row, via ResolveEnvironmentPrecedence) and stamps the resolved list verbatim on every entry of that tenant, the same policy-stamping pattern as envfilter. When no row is set at either scope it stamps nothing and the plugin applies the built-in default order above, which is also what an estate behind an un-rolled daemon gets. One wire corner, recorded on launcherEnvironmentPrecedenceForTenant: the field is omitempty, so an explicit empty list (“no preferred order”) rides as absent and the plugin falls back to its default, while the web console, which reads the config key directly, honours it.

17. Placement: launcher_placed and launcherPlaced, both halves real

Section titled “17. Placement: launcher_placed and launcherPlaced, both halves real”

Whether a deployment is a launcher DESTINATION at all. Two halves, one axis, both shipped as of ce 4a67b0c5:

  • The app.yaml half: launcher_placed: false, top level, bool grammar (ce 5ceafded). A property OF THE APP: an app whose routed host exists to be called rather than opened (the measured case that forced the key was nextcloud-picker; that sidecar now uses belongs_to so it can ride Nextcloud’s menu, and the remaining declarer is gitlab-huly, a webhook with no page) declares it at package time, the same argument that put host_roles: in the catalogue. Absent means placed.
  • The scoped config half: the launcherPlaced key (ce 4a67b0c5), the operator override: resolved per deployment through the five-tier cascade like launcher/launcherGzip, and a row at ANY scope wins over the app.yaml default in both directions: false unplaces an app the catalogue placed, true places one the catalogue opted out. Absent everywhere means placed. Bool grammar only; the value domain refuses anything else at shc config set time (the launcher on defect, pre-empted), and a pre-declaration typo row degrades to the app default rather than moving a tile.

The wire: stamped, never dropped. The first ce cut (5ceafded) dropped an unplaced deployment’s entries from apps.json outright. That was retired the day the config half landed, because the file is ALSO the authority menuTenantOf resolves “which tenant owns this host” from; a dropped entry cost the unplaced app’s own pages their injected launcher and answered its host a bare 401, an outage wearing a preference’s clothes (the same argument that keeps envfilter-excluded entries in the file, §7). So BuildAppsMenu now stamps the entries:

wire keyplaced, on each apps.json entry, omitempty
valuefalse is the ONLY value ever written; placed rides as an absent field, so an estate that never touches the axis produces byte-identical files
plugin sidefilter unplaced entries with no parent out of the LIST; sidecars that belongs_to a parent still reach foldMenuStack so they can ride that tile’s menu (§20). Tenant resolution still sees every entry
absentplaced; every daemon predating the field writes nothing

Mid-roll honesty: a plugin image predating the field ignores the stamp and renders the tile again, so an estate that rolls the daemon before the Traefik image sees the embedded-iframe tile RETURN until the image rolls. Cosmetic, bounded by the roll, and deliberately preferred over the drop’s failure mode (a broken launcher on the unplaced host for as long as the key is set, on every plugin version). The plugin’s list filter is now real: serveLauncherApps drops placed: false entries in the same visible loop as the tenant and envfilter predicates, keeps them for menuTenantOf and injection, and both directions are pinned in menu_inventory_test.go (TestPlacedFalseDropsTheTileAndNothingElse, TestAnUnplacedHostStillGetsTheLauncher).

18. The launcher shell: two shells, one bootstrap (ruled 2026-08-13)

Section titled “18. The launcher shell: two shells, one bootstrap (ruled 2026-08-13)”

The approved two-shell architecture: the plugin’s injected bootstrap stays a small pinned constant (the byte-ceilinged payload of §12.8), and the fullscreen panel it opens is replaced by a CSR launcher shell, a real bundle, served same-origin by the plugin from a DAEMON-MATERIALISED file, so shell iterations ship with ce releases and never need a plugin image repin. The bootstrap keeps its built-in vanilla panel as the permanent fallback: the shell is an upgrade, never a dependency.

The endpoint-namespace widening (owner ruling 2026-08-13). The plugin serves /.shc/launcher/shell/* (static, content-addressed files only, no dynamic behaviour) as the fourth reserved prefix beside §3’s three endpoints. Same-origin for the same reasons as everything else in §2 (no CORS surface, no third-party fetch, no CSP concession naming a foreign host).

The materialisation contract (ce 6ccb71d9, ce/modules/app/launcher_shell.go). The daemon side of the same doctrine that ships apps.json and the icons: the file is the interface, the plugin’s only I/O is reads off the license mount. Rendered by every build of the clusterfs licence section, atomic (temp+rename), content-idempotent, ASSETS BEFORE MANIFEST so a build can never hold a manifest naming a file that is not in it.

manifest<licence section>/launchershell/manifest.json: {"version":1,"js":"<name>","css":"<name>"}; css may be absent (inlined styles), js never is
version1; the plugin ignores any other value. Additive fields need no bump
assetssibling files in the same directory, content-addressed: the name IS the sha256 of the bytes
name rule`^[0-9a-f]{64}.(js
servingContent-Type by extension table (two entries, closed set, never sniff); names are digests, so Cache-Control: immutable-class caching is sound; superseded assets stay on disk (the plugin re-reads the manifest on its own TTL, and deleting old names is the only way a roll can 404)
absent/unreadable manifestNO SHELL; the bootstrap keeps its built-in panel. Never an error a user sees

Where the bytes come from. ce/core/launchershell, an embedded asset in the ce binary. ce alone ships a PLACEHOLDER (a tiny script that logs and leaves the built-in panel in charge); the shc build injects the real bundle via launchershell.SetBundle(fs.FS) with shell.js (required) and shell.css (optional) at the FS root. The hashed stored names are computed by the materialiser from the bytes, so no hand-maintained hash exists anywhere. The real shell build is the springboard-ui extraction lane’s deliverable; until it lands, every estate materialises the placeholder and nothing changes visually.

19. The plugin’s shell half: serving, the loader, the fallback

Section titled “19. The plugin’s shell half: serving, the loader, the fallback”

The plugin side of §18’s contract (traefik/plugin/shell.go, and csr() in the payload). The bootstrap keeps the trigger, both OIDC legs and the credential ladder exactly as they are; what changes is what an OPEN renders. This is the two-shell shape: the byte-ceilinged bootstrap is the outer shell that must land on anyone’s page under anyone’s CSP; the CSR bundle is the inner shell that may grow like an application, because it rides its own endpoint and never the injected constant.

GET /.shc/launcher/shell/<name>, reading /shc/license/launchershell/<name>, and every clause is load-bearing, the same discipline as the appicons contract (§12.8.1):

  • The name is matched against §18’s rule (the plugin’s shellValidStoredName, yaegi’s reimplementation of app.ValidLauncherShellName) before it is joined to the directory.
  • The bytes are re-hashed and must equal the name. The response is cached public, max-age=31536000, immutable (the name is the version), so a torn read of a mid-write file must become a 404 and a vanilla panel, never a browser’s forever copy of garbage.
  • Content-Type from the extension by closed table (text/javascript / text/css), never sniffed; X-Content-Type-Options: nosniff; a default-src 'none' CSP on the asset response itself.
  • No identity required. The assets are static, content-addressed and carry no data; the names ride only the authenticated /apps response, so an anonymous visitor learns nothing, not even a digest.
  • One refusal shape: 404, no body, no-store, malformed name, missing file, oversized file and digest mismatch alike.

The manifest is read on the same TTL and last-good rules as apps.json, and it is honoured whole or not at all: a malformed name anywhere in it reads as “no shell” and the estate keeps the vanilla panel.

On the /apps response, as an additive shell field (launcherShellRef, short keys j/c), not a manifest endpoint. Same reasoning that put the glyph sheet there: the bootstrap needs the names exactly once, at the moment it already holds an answered inventory, and a fetch that already happens once per page view is cheaper than a new unauthenticated JSON endpoint in the reserved namespace plus a second round trip and its own failure mode. The bootstrap being a compile-time constant is what rules out embedding the hashes in the page: a per-estate byte in the payload would break the constant-CSP-hash property everything else rests on.

csr() in the payload runs on the first open only. A visitor who never presses the trigger costs nothing. It fetches the CSS as text and applies it through new CSSStyleSheet() + adoptedStyleSheets on the shadow root (a <style> element would be an inline style for CSP purposes; a constructed sheet needs no directive at all), then injects <script src="/.shc/launcher/shell/<hash>.js"> non-parser and calls the bundle’s window.SHCLauncherShell.mount(el, {apps, data, close}): the mount point inside the same shadow root, the same-origin /apps path, the inventory the page already holds, and the close function the trigger and Escape share.

Every failure falls back to the vanilla panel, and none is dark: no manifest on the mount, an engine without constructable stylesheets, a CSS fetch that dies, a script that 404s or is refused, a script that defines no mount() (ce’s placeholder, a stale cache), and a mount() that throws. One attempt per document (a failed bundle is not re-fetched on every press) and nothing tab-scoped is written (the anti-latch rule stands). The guards drive the real payload through node (launcher_shell_node_test.go): a placeholder shell through the full path, and the panel through every fate above.

An external same-origin script is governed by the page’s script directive, and a hash cannot admit a src= load. The cooperation path grew a fourth editor (cspRelaxScriptSources): when, and only when, the mount actually carries a shell, the injector claims https://<host>/.shc/launcher/shell/, this origin, path-bounded to the plugin’s own namespace, never a bare 'self'. The merge is monotone (a host source never disables 'unsafe-inline' the way a hash does), never touches a 'none', and appends nothing to a policy that already admits the load: SonarQube’s measured policy carries 'self' and comes out byte-identical, which is pinned by test. Policies with 'strict-dynamic' need no claim at all; the hashed bootstrap inserts the shell script non-parser, which strict-dynamic trusts transitively.

The loader added 1,350 bytes to the injected constant (10,318 → 11,668, over the always-label lane’s landing), all of it addition because the fallback doctrine keeps every byte of the vanilla panel shipping. Simplification came first (the first cut’s duplicated XHR helper was folded into get() as a raw flag, −220), and the ceiling was raised 10,350 → 11,700 with the arithmetic written over menuPayloadByteCeiling, per the standing rule that a raise carries its justification in the test.

The bundle (separate lane; ce ships a placeholder until then) must:

  • be a single classic-script .js (plus optional .css) that defines window.SHCLauncherShell.mount(el, opts) and renders into el;
  • read its data through opts.apps (the same-origin inventory path) and treat opts.data as the already-answered first load;
  • call opts.close() to dismiss; the bootstrap owns the trigger, focus return and the Escape key;
  • carry no absolute origins; everything it fetches must be same-origin under the page it lands on;
  • ship as shell.js (+ optional shell.css) injected through ce’s launchershell.SetBundle (§18); the materialiser computes the content-addressed stored names, and the plugin refuses anything whose bytes do not hash to its name.

20. One tile per stack: sidecars, vapps, extra environments

Section titled “20. One tile per stack: sidecars, vapps, extra environments”

Clay’s ruling of 2026-08-14, restating Q1: one icon per STACK. Extra deployments, vapps, and plugs that are not the primary UX belong in that tile’s right-click (or long-press) menu, never as their own tile.

Entitlement is still per deployment. dedupeMenuTiles still keys on (tenant, environment, stack). The three Frappe benches (bit, erpnext, ffx) stay three tiles because they are three stacks. What changed is DISPLAY of the extras that used to sit beside them.

ExtraHow it reaches the menu
Extra environment of the same stackdedupeMenuEnvironments keeps the precedence winner as the tile and appends the loser as k kind e
Sidecar stack (nextcloud-picker)catalogue belongs_to: nextcloud; daemon stamps belongsto; plugin foldMenuStack (baked fallback covers an un-stamped live file)
Installed vapp instancealready stamped as vapps on the parent entry; copied onto k kind v (no href; no routed host)
Webhook / no UX (gitlab-huly)launcher_placed: false, no parent, omitted, not folded

Wire on the inventory tile: k: [{n, h, p, t}]. t is e (environment), s (sidecar), or v (vapp). The vanilla overlay’s arm() opens that list on contextmenu and on a 500ms long-press. A sidecar with no matching parent tile stays a tile (picker without nextcloud). Two or more parent tiles of the same catalogue app in one environment (the frappe benches) leave a sidecar that named that app unfolded; folding onto bit because it appeared first would hide it behind the wrong company’s books.

21. The launcher’s design law: the standing owner rulings

Section titled “21. The launcher’s design law: the standing owner rulings”

The rulings that shape the overlay, in one place, so a session that touches the launcher can cite the rule it is following (or the one it is about to ask the owner to change). Each entry names the ruling, the date and the code that enforces it.

  1. Literal iPad springboard. The overlay reads as an iPad Home Screen (wallpaper, squircle icon field, glass dock shelf), not as a file picker. (2026-08-14; dress() in menu_homescreen.go, guarded by menu_homescreen_test.go and the fill/scroll node harness. The page dots that shipped with it are gone: §21.5’s Ruling 3 replaced the page strip they indexed with one vertical scroller.)

  2. One icon per stack. A stack is one tile; extra environments, sidecars and vapps ride that tile’s right-click / long-press menu (§20). (2026-08-14; menu_stack.go.)

  3. X-only dismissal. The Applications overlay closes on its close control, on Escape (keyboard a11y, the keyboard user’s X) and on activating a tile. It NEVER closes on a press of its own background: the overlay is a workspace, not a transient popover, and on a phone the empty space between icons is most of the screen, so a backdrop dismiss made every missed tap close the workspace. (2026-08-16, reported from mobile Safari on the live corp estate; the removed handler was if(e.target===pane||e.target===grid)shut() in menu.go, and TestLauncherOverlayDismissesOnXOnly refuses its return.)

  4. No wiggle mode. “We don’t even need a wiggle mode.” There is no in-launcher edit mode of any kind: no long-press-to-edit, no jiggle animation, no drag-to-reorder, no drop-to-folder, no per-user layout persistence. Icon arrangement is whatever the served inventory says (BuildAppsMenu’s order); changing it is a config change, not a gesture. (2026-08-16; the ruling removed menu_arrange.go, launcher_layout.go and the PUT leg of /apps whole; TestLauncherHasNoWiggleMode (since narrowed and renamed; see the amendment below) refuses the chrome’s return. The mode’s reproduced defects are recorded below so nobody rebuilds it “fixed”: blank unmarked folder tiles, a blocking window.prompt rename whose answer never reached the caption, a near-transparent folder board the springboard bled through, an outside-tap that closed the overlay and latched the stale board over the next open, and a 400ms/500ms long-press collision that fired edit mode and the §20 extras menu from one hold.)

    ★ AMENDED 2026-08-16: the scope was read too wide

    Section titled “★ AMENDED 2026-08-16: the scope was read too wide”

    The clause above is superseded in its scope and kept in its defect list. It banned folders, drag-to-reorder and drop-to-folder along with the jiggle; the owner’s correction, the same day and verbatim:

    “When I say no wiggle mode, I still want the ability to have folders. They’re not incompatible. Right? Like, the no wiggle mode, it’s not even called no wiggle mode. It’s just where don’t do the wiggle. And you can press and drag into folders or press and drag around, or you can just click press it or click on it, and it opens. Or you can right click on it or long press on it, and it pops up the menu. But we shouldn’t need a wiggle mode to do any of that.”

    What the ruling actually bans, and it is two things:

    • the jiggle: no rotate interval, no shc-jiggle, no animation of any kind on a resting tile; and
    • the mode: no entry point, no state to be in, no way out. There is no hold-to-enter-arrange, no edit flag, no “done” affordance.

    What it does NOT ban: folders, drag-to-reorder, drop-to-folder, or a per-user arrangement that persists.

    The target is DIRECT MANIPULATION with no mode at all. One pointerdown on a tile resolves to exactly one of three outcomes, on two independent thresholds:

    gestureconditionoutcome
    tap / clickrelease with travel ≤ 8px before 500msthe app opens, unchanged
    press and dragtravel > 8px, at any timethe tile moves: reorder, or drop dead-centre on another tile to make a folder
    long-press / right-click500ms elapsed with travel ≤ 8pxa context menu pops up (Open, or Rename on a folder, plus the §20 extras)

    They are mutually exclusive by construction, not by luck: movement past the slop CLEARS the pending hold timer, and a fired hold latches CM so pointermove returns early. TestFoldersHoldAndDragCannotBothHappen is the assertion that neither half can be deleted quietly.

    The recorded defect list above is unchanged and is now the acceptance criteria. Each is proven absent by a named test in menu_folders_node_test.go, driven through the node vm.Script stub DOM against the SERVED payload:

    defecthow it is answeredtest
    blocking window.prompt rename whose answer never reached the captioninline <input> above the open board; commits on blur and Enter, reverts on Escape, writes cap.textContent, persistsTestFoldersRenameIsInlineAndReachesTheCaption, TestFoldersRenameEscapeReverts
    blank unmarked folder tilesmini() paints up to four MEMBER pictures through the same glyph() the tiles use, repainted on every membership changeTestFoldersDropOntoTileFormsAFolderAndOpensIt
    near-transparent folder boardopaque #0d1426 board over its own 72% scrimsame test
    outside-tap closed the overlay and latched the stale boardthe tap lands on the SCRIM and closes the BOARD only; shutF() REMOVES board, scrim and input and nulls every handle, and openF() calls it firstTestFoldersCloseTearsDownAndNeverLatchesTheStaleBoard
    the 400ms/500ms long-press collisionthere is now exactly ONE hold timer in the payload; menu_stack.go no longer installs its own touch long-press and only records the tile’s extrasTestFoldersHoldOpensTheContextMenu

    Also built, from the owner’s description: forming a folder OPENS it immediately; tiles reorder inside an open folder with the live reflow preview (neighbours shift out of the way DURING the drag off a frozen grid, shift back if the finger returns, and commit only on release); the dragged tile is ghosted at 0.6 opacity with a slight scale; a dead-centre hover shows a distinct folder-forming ring (shc-fd) against the between-tiles reorder state (shc-mv); a tile carried beyond the board’s bounds returns to the page; and a folder down to one member collapses back to a plain tile IN THE FOLDER’S OWN SLOT.

    A fourth defect, reported separately and fixed here: a long-press raised the browser’s native text selection over the tile. The panel sets user-select, -webkit-user-select, -webkit-touch-callout and -webkit-tap-highlight-color; the rename input sets user-select: text back, because a field you cannot select in is a field you cannot rename in. (TestFoldersSelectionIsSuppressedOnThePanel.)

    What did NOT come back, and stays refused by TestLauncherHasNoWiggleAndNoPrompt: shc-jiggle, W.setInterval (the jiggle’s engine), prompt(, 'PUT' (the layout is localStorage-only, per host; re-adding a mutation to /.shc/launcher/ means designing CSRF for the most widely exposed surface SHC has), and shc-home- (the retired per-user key prefix). TestLauncherHasNoEditMode pins the other half: that the payload’s one hold timer opens a MENU and that the tile click is gated on the two gesture latches rather than swallowed unconditionally.

    The code is menu_folders.go (home()), spliced at IIFE top level beside dress() and grab(). Payload cost: 16,400 → 28,100 on the ceiling, measured 27,835, itemised on menuPayloadByteCeiling.

The long-press that REMAINS is §20’s extras menu, now folded into the launcher’s single context menu; the payload has exactly one hold timer and one popup, which is what retires the collision recorded above.

21.5 The gesture model: four rulings, one recogniser (2026-08-16)

Section titled “21.5 The gesture model: four rulings, one recogniser (2026-08-16)”

Four rulings arrived together and they are one gesture model, not four tickets. The first is the root one and the other three are unsatisfiable without it.

Ruling 1: a drag arms on the LONG-PRESS, never on touchdown. “You shouldn’t be able to drag an app until holding long enough for the menu to open. That way normal scrolling scrolls the window.” Until this lane every tile carried touch-action: none and was armed from pointerdown, so a swipe that started on a tile dragged the tile instead of scrolling the field. The hold that already raised the context menu now also arms the drag (one timer, one recogniser, one source of truth), and one pointerdown becomes exactly one of four things:

outcomeconditionthresholds
TAPrelease under slop before the hold firesT = 8dp
SCROLLtravel > T before the hold firesT = 8dp, HD = 500ms
MENUHD elapses under slopHD = 500ms
DRAGtravel > T after HDT = 8dp

The cancellation rules are what make it feel native, and each is guarded by name:

  • movement past T with the timer pending cancels the press: the timer is cleared, the stream released, and nothing is preventDefault()ed, so the gesture belongs to the scroller (TestFoldersSwipeOnATileScrollsAndDoesNotDragIt);
  • that cancelled press also does not launch the app on release (iOS and Android both cancel the activation at the same slop) and the swallow is one-shot, so the next tap opens it;
  • a completed press suppresses the click its release would fire (CM), and stays armed until release even if the finger rests (TestFoldersHoldThenStillDragsAfterAPause).

touch-action alone is advisory once a gesture has begun (a browser fixes the effective value at touchstart), so a non-passive touchmove listener on the panel takes the gesture back while armed, and does nothing at all otherwise.

A mouse arms immediately. A mouse drag cannot scroll anything, so there is no scroll to protect and a hold would only cost the desktop pointer drag a prior lane fixed. One documented exemption (e.pointerType === 'mouse'), not a second model (TestFoldersMouseDragNeedsNoHold).

Ruling 2: a drag closes what is open over it. “When I long press and the stack menu opens, when I drag another icon the stack menu should disappear.” The stack menu is dismissed by a document-capture click and a drag fires no click, so it used to hang over the field pointing at a tile that had moved; m.hide (its own teardown, listener included) is now called the instant a drag begins. The folder board closes with it, except for a drag that STARTED inside the board, which is drag-out and must not have its container deleted mid-flight. And because the board’s scrim covers the pane at z-index 7, a press aimed behind it never reaches a tile at all: the scrim now closes the board on pointerdown as well as on click, which is what makes the ruling true for a finger rather than only for a synthetic click.

Ruling 3: overflow scrolls DOWN; the page strip is retired. “What happens when there are more apps than the window holds? I guess they just vertically scroll down because screen sizes are dynamic.” What this replaced was deliberate: .shc-pages, scroll-snap and a page-dot row, i.e. a faithful iPad springboard. The argument for changing it is the owner’s own and it is a correctness one: a page has a capacity, and capacity is measured from a viewport that moves. cols×rows is recomputed on every resize, the stored layout is per page (L.p[]), so every rotation re-cut the boundaries and split what the user arranged. One scroller has no boundary to move.

The row UNIT is load-bearing and was caught only in a real browser: with repeat(rows,1fr) an overflowing field simply compresses its rows to fit (measured at 390×844: rows 91.9/67.0×5/95, scrollHeight 642 = clientHeight 642; overflow-y: auto with nothing to scroll). The overflowing field re-declares the same tracks in PIXELS.

Ruling 4: the favourites bar scrolls sideways. “If the favorites bar can’t fit everything it should horizontally scroll.” overflow-x: auto, flex-wrap: nowrap, a fixed 60px icon (never shrunk below the touch target) and (the part that took two attempts) justify-content: safe center rather than a measured flip: plain center on an overflowing row put the second of nine entries at x = −39, off the scrollable origin, and a measured version could not see the dock at all because lay() runs before apply() restores it. dropAt()’s four-item cap and its eviction branch are gone with it: the bar never silently drops an entry.

The two axes are kept apart by the browser, not by a JS guess. The field declares touch-action: pan-y, the bar pan-x. Neither is a scroll container for the other, so there is no chaining to arbitrate and a diagonal swipe at the boundary cannot drive both.

Proven in a real Chrome at 390×844 with real touch input (32 stubbed apps, 28 on the field): a swipe starting on a tile moved the field 0 → 143px with the order unchanged and no tile translated; a 750ms hold raised ["Open"]; the following drag ghosted the held tile, translated two neighbours and closed the menu; the drop reordered; a dead-centre drop formed and opened a folder; a press on the scrim closed the board on pointerdown; a drag out of an open folder kept the board up and collapsed it on release; and a horizontal swipe on a nine-entry bar moved scrollLeft 0 → 232 while scrollTop stayed 0.

Payload cost: −185 bytes (31,180 → 30,995 measured on the rebased tree; the ceiling stays 31,500). Ruling 3 deleted more than Rulings 1, 2 and 4 added, because the gesture work reuses the hold timer that was already there.


22. Surviving the app: mounting, removal, and the retry ladder

Section titled “22. Surviving the app: mounting, removal, and the retry ladder”

Measured on bitspur 2026-08-16 with a real browser holding a real corp session, across all 33 routed hosts in apps.json. Two failures were found, and neither one is an identity failure, a routing failure, a CSP failure or a gating failure. Both are “the marker is in the served HTML, the payload ran, and the user sees nothing”, which is the shape §7’s ladder was built to end, and did not.

22.1 The app owns the DOM, and the payload assumed it did not

Section titled “22.1 The app owns the DOM, and the payload assumed it did not”

siem.corp.bitspur.com (Wazuh) ran the payload to completion (both /.shc/launcher/apps calls, 401 then 200, are in the router’s own access log), and when the page settled neither the injected <script id="shc-apps-menu"> nor <div id="shc-apps-launcher"> was in the document. A MutationObserver armed at document start on documentElement with subtree: true recorded no removal, which is the tell: the nodes were never removed from the live tree, they went away with the body they were in. Wazuh replaces document.body.

The payload used to capture the body ONCE, at IIFE time:

var B=d.body||d.documentElement;

so after the swap B is a detached node, and B.appendChild(root) mounts the launcher into a tree that is no longer in the document. Present in memory, correct in every other respect, invisible on screen, silent in the console, and indistinguishable from every other “menu absent” report.

Two changes, both in menuBootstrapScript:

  • B() is a function, read at use time. A body swap can no longer strand the mount.
  • keep(root) arms a childList, subtree:false MutationObserver on exactly two nodes (<html> (fires only when <body> itself is swapped) and the body the root currently lives in (fires only on its DIRECT children)), debounced onto one zero-delay timeout. A framework patching inside its own mount point, which is what a render is, fires neither. On a fire the whole test is d.contains(root).

It gives up rather than fight. menuReattachCap (20) bounds the restorations. An app that removes the root in a loop and a payload that re-appends it in a loop is a flicker and a busy loop on a page this repo does not own, strictly worse than the absent launcher it is fixing. TestLauncherStopsReattachingRatherThanFightTheApp asserts the giving-up half; TestLauncherSurvivesAClientSideRerender asserts the other.

22.2 un was an outage treated as a verdict

Section titled “22.2 un was an outage treated as a verdict”

probe’s un bit is /start answering 503 identity-check-unavailable, which serveLauncherStart returns for exactly one reason: the daemon could not be reached for realm-for-host inside gateAuthzTimeout. It is a statement about the ESTATE at one instant, never about the caller.

The payload answered it by rendering neither the menu nor the sign-in offer, and never asking again for the life of the document (§6’s “two cases render nothing”). So one slow daemon call cost the user a launcher until they happened to reload, and there was nothing in the page, the console or the network panel that said so.

From bitspur’s retained access log on 2026-08-16: 24 of ~70 /.shc/launcher/start requests answered 503, spread over ten hosts including grc, design and fleet.

The boot flow is now a bounded ladder (2s, 8s, 30s) down the un branch only. Every other outcome keeps its existing behaviour, because every other outcome is DECIDED rather than transient:

outcomebehaviourwhy not retried
inventory answeredbuildflow() is guarded by getElementById and never re-enters
proven, no tilesnothingan empty launcher is worse than none; re-asking cannot change it
not proven, not unthe sign-in offerthe offer IS the affordance; a timer behind it is a request nobody asked for
unretry, ×3the daemon was down, and daemons come back

A healthy estate pays nothing: the retries exist only on a page that already failed. TestLauncherRetriesWhenTheProxySaysTheCheckIsUnavailable and TestLauncherDoesNotRetryADecidedAnswer are the two halves.

33 routed hosts, one browser, one corp session, settled page:

  • launcher rendered: knowledge, grc, sbom, sbom-api, fleet, git, glitchtip, projects, llm, mail, matrix, matrix-auth, meet, mautic, design, artifacts, workflows, cloud, chat, quality, marketplace, api.marketplace, hq.flyingfoxlabs.
  • injected, ran, invisible: siem, §22.1, now fixed.
  • sign-in offer rather than the menu: marketplace, api.marketplace, hq.flyingfoxlabs, expected, §8’s mixed registrable domains.
  • never injected: hq, erp (Frappe, §8’s SSO-selector route, known and unfixed), gitlab-huly (launcher_placed: false, correct), errors, license.selfhostedcloud.org, picker, and the gated idm / agents / openreplay. Coverage of those belongs to the flagship-coverage lane, not here.

Owner, 2026-08-16: “Also I need a profile icon and link to go to settings and one to go to console.” He asked twice before, in different shapes: “shouldn’t there be, like, a user profile that when pressed goes to the console” and “isn’t there supposed to be an app called settings and an app called marketplace”.

Source: traefik/plugin/menu_profile.go, whose header carries the whole argument; this section is the estate-facing summary.

AMENDED 2026-08-18: the sheet is gone. The owner withdrew the dropdown: “i don’t want this dropdown menu on the floating menu. instead clicking the icon should take me straight to the console.” The chip is now an anchor whose href is the console, and Account and the refusal rows are deleted rather than hidden. Everything below about the SHAPE (chrome, not a tile) and the SOURCE of the identity still stands; the parts about the sheet’s rows are history. §27.5 has the amendment and the edge cases.

AMENDED AGAIN 2026-08-21: the door is the account profile. The avatar opens <issuer>/account/ on the launcher and in the Console alike, and the URL is the CALLER’s realm, published by the daemon on /api/user/effective-apps. §27.5.1 has it.

23.1 The shape, and why it is not three tiles

Section titled “23.1 The shape, and why it is not three tiles”

Ruled here: the profile is FIXED CHROME in the panel header. Settings and Console are entries in the sheet it opens. None of the three is a tile.

The middle phrasing above asks for tiles, so the shape had to be decided rather than guessed. Two reasons decided it, and the second is the one that would have shipped a defect:

  1. A tile can be buried. As of §21.4 every tile is draggable from the moment it is built and a tile dropped on another becomes a folder. That is the feature. It also means anything in the field can be put inside a folder called anything, and this launcher has no app drawer, no search and no reset-layout verb, so the grid is the only index there is. For an ordinary app that is intended. For “who am I signed in as” it is not: an identity affordance the user can lose is one that cannot be trusted to be checked. Every system that ships one puts it in fixed chrome, and none of them makes it a home-screen icon.
  2. A tile must open something, and neither of these opens anything today. Measured 2026-08-16 on this tree: there is no settings app in the catalogue: 103 app directories under apps/, not one named settings; deploy/shc/ holds exactly marketplace and portal. And nothing serves the console on any estate: no daemon serving route, no deploy/ stack, no catalog entry; apps/console is a build workspace CI typechecks (MR !45 measured the same from the licensing side and TIERS.md records it). A settings tile and a console tile would both point at nothing. (Update 2026-08-20: the console half expired the same day; 8bc18cc8c landed the serving route, traefik route and launcher entry, which is this section’s “door” swinging open exactly as the next paragraph describes. The settings half of the measurement still stands.)

marketplace, which the owner named in the same breath as settings, is the contrast that makes the finding legible: it is a routed stack with a host, which is why it already has a tile and vendored art. The launcher tiles what the estate ROUTES.

The door is left open both ways, and it needs no switch. The moment an estate routes a console or a settings stack, apps.json names it and the launcher tiles it automatically: first-class, draggable, foldable, like any app, with no code change. The profile row does not become redundant then; it becomes the unburiable route to the same place. That is the honest reading of “both”: tiles for what the estate routes, header chrome for what must always be findable.

TestProfileChipIsHeaderChromeNotATile holds the position in the DOM three independent ways (parent is the header; no ancestor is the field; the drag machinery has not armed it). TestNoSettingsAppExistsInTheCatalogue holds the measurement, and fails the day somebody creates a settings app, a prompt to re-read this section, not a regression.

23.2 Where the identity comes from: nothing new

Section titled “23.2 Where the identity comes from: nothing new”

/api/user/effective-apps answers {"version":1,"user":"…","apps":[…]} and menuClient.fetch had been decoding that user and throwing it away since the endpoint was adopted (§7). It is now carried through the verdict cache onto the response. No extra daemon call, no new endpoint, no header, no cookie.

That choice is load-bearing rather than tidy. The plugin’s other identity (menuIdentity.User off the forward-auth proof) is empty for most real users: the entitled-elsewhere rung reaches the inventory precisely because forward-auth refused them, and it used to construct &menuIdentity{Tenant: tenant} with no user at all. On bitspur that is 42 of 43 realm users. A profile built on the proof header would have been blank for almost everybody while every idAdmits test stayed green, this subsystem’s signature defect. TestProfileNamesTheUserOnTheRungThatServesRealPeople is written against idRefuses for exactly that reason.

The name rides the private inventory response (me.u), never the injected payload, which stays a caller-independent compile-time constant. TestTheProfileBlockIsNotInTheInjectedBytes names it.

23.3 Settings = the realm’s account console

Section titled “23.3 Settings = the realm’s account console”

There is no settings app to link to, and the console’s own settings screen (apps/console/routes/settings.tsx) is inside the console and therefore behind the Hobby gate; pointing Settings there would put the one surface every user needs behind the one gate that was just added.

So Settings is the Keycloak account console of the realm that gates this host: {issuer}/account/. It is real, deployed, per-user, on every estate this product has stood up, ungated at every tier, and it is the settings of the identity the chip above it names. The issuer comes from the same realm-for-host lookup the silent check already makes (§6), cached per host for 30s, misses included; 24 of ~70 realm lookups answered 503 in one bitspur window (§22.2) and an uncached miss would re-ask on every page view.

An unresolvable realm means no Settings row. This plugin has refused to guess an issuer since §7 was written; a settings link into a hostname nobody verified is that same defect with a friendlier face.

23.4 The console’s tier constraint: asked, never re-derived

Section titled “23.4 The console’s tier constraint: asked, never re-derived”

Owner ruling 2026-08-16: “No console requires at least hobby.” MR !45 landed it as the console feature key behind one daemon door, shc.console.gate (modules/console/gate.go).

The launcher asks that door, with the caller’s own credential, the same credential the verdict call already carries to the same daemon on the same request. It derives nothing itself, and could not: license.go in this plugin reads posture (keyed / trial / degraded) and knows nothing about tiers, so a local decision would be a guess wearing a gate’s clothes. The daemon’s own header says why a client must not answer this: a client-side GateRefuse resolves StateUninitialized, which is permissive by no-brick doctrine, and would wave everyone through.

gate answersthe row is
200a live link, if this tenant also routes a console the caller may open
200, nothing routedthe sentence “not deployed on this estate” (the state every estate is in today)
403 X403029LICENTa refusal naming Hobby, with the shc license status pointer
403 X403036LICOPTnever licensed, so the trial pointer, not a renewal
403, any other codeno row; an authz 403 is not a licensing claim
404 / 5xx / unreachableno row; a community daemon does not carry the route (absence doctrine), and a daemon that did not answer has told us nothing

The last two rows are the point. Painting “requires Hobby” off a transport failure would be a licensing claim invented by a proxy, and the estate reading it could not tell it from the truth.

The refusal is never an anchor. The row is an <a> when there is somewhere to go and a <div> when there is only something to say: TestProfileConsoleRefusalIsNotAnAnchor drives the payload and fails if one href= appears in the wrong branch. That is the runtime no-brick contract at the last place it can still be broken.

Both questions must pass. The estate’s entitlement is the gate’s; the caller’s permission is the RBAC verdict’s. The console link is built from the tiles the caller is already being shown, so a console the caller holds no role on is not linked even on an entitled estate.

What this deliberately does NOT do: filter TILES by entitlement. If an estate routes a console stack, that host keeps its ordinary tile whatever the licence says. Three reasons, and they are the same reason three times: the tile comes from apps.json, which is the daemon’s routing record and says the host serves something; the console’s own bootstrap consults the same shc.console.gate and shows its own refusal on its own surface, which is where a product’s paywall belongs; and a launcher that filtered tiles by entitlement would be making a licensing decision per app, which is a far larger claim than this subsystem is entitled to make. The profile row is the launcher’s own affordance and is the one thing here that must not lie about the tier.

23.5 The copy lives on the wire, not in the payload

Section titled “23.5 The copy lives on the wire, not in the payload”

Every sentence a user reads about the tier is built server-side onto the private inventory response (launcherProfile.ConsoleNote). That response is no-store, same-origin and fetched once per page view; it has no byte ceiling. The payload’s entire share of the tier constraint is p.c ? link : p.cn: two branches, no strings.

Had the copy ridden the payload it would have cost every anonymous visitor on every host of every estate several hundred bytes to carry a sentence none of them can read. TestTheProfileCarriesNoCopyInThePayload refuses it, and refuses being satisfied by deleting the feature.

menuPayloadByteCeiling 29,000 → 31,500, measured 31,041 served bytes (28,651 + 2,390). The 2,390 is one payload function, who(): the header chip, the sheet it creates and removes, and the two rows. The constant’s own comment carries the decision, as §14’s raise required of every raise after it.


24. The press must survive the sign-in (ruled 2026-08-16)

Section titled “24. The press must survive the sign-in (ruled 2026-08-16)”

Owner: “when I press the floating menu and I’m logged out it redirects me to login which is correct but then when it redirects back it doesn’t open the menu for me so I have to press it again.”

The sign-in worked. The intent was lost. The signed state carried u (the callback URL), r (the realm), i (issued-at) and t (the return path), nothing that said what the user was asking for. So the callback could bring the user back to their page but not back to the thing they pressed: the page reloaded, /apps now answered, and the menu rendered shut beside a user who had already asked for it open.

In the signed state, as o, and nowhere else. The callback honours only what /start provably minted (that is why t rides there), and an unsigned query parameter would let any link on the internet make somebody’s launcher pop open. It is only a UI hint; it is still not allowed to be the one unsigned input on a path built to trust nothing unsigned.

The two entry paths behave differently, and that is the fix

Section titled “The two entry paths behave differently, and that is the fix”

/start already knows which leg it is on:

LegQueryMay carry intent
top-level click-through?open=1&return=<path>yes; a human pressed
framed silent check(none), or ?silent=1no, ever

The silent check runs unbidden on every page view of every injected host. A dialog springing open off one would be a worse defect than the one being fixed, so /start drops open=1 on that leg even when it is written straight onto the URL: wantOpen := interactive && …. The flag means “a human pressed”, never “this leg is top-level”; the two coincide today only because the press is the sole thing that navigates.

The callback answers a proven press by setting shc_launcher_open=1 beside the 302 home. The payload reads it and deletes it in the same breath, at document scope, before anything asynchronous runs.

  • the address bar, history entry and Referer are exactly what the user left; nothing is appended and nothing has to be scrubbed;
  • a reload finds nothing;
  • a back-button navigation finds nothing;
  • a second tab on the same host finds nothing;
  • the intent is spent even if no menu renders; an intent nobody could honour must not queue up for later.

A failed round trip (login cancelled, no code, a state that did not verify) mints nothing: there is no menu to open, and the sign-in offer is what should render.

This is not the tab-scoped latch §22’s anti-bounce rules forbid. That ban is on the payload minting a suppression latch for itself. This is a server-issued token of an intent the server watched complete, valid for one document, destroyed on read; the only thing the payload writes is the deletion.

Driven end to end in node against the served bytes (launcher_intent_node_test.go): one cookie jar, three page loads: open on the first, closed on the second and third, and an ordinary press still opening the menu on the reloaded page.


25. One layout, per user, on every host (ruled 2026-08-16)

Section titled “25. One layout, per user, on every host (ruled 2026-08-16)”

As of FZ-8531, the app-host /layout write route is retired. /apps returns the stored revision and arrangement, but no write token: the compact lay.t field (formerly launcherLayoutState.Tok) is absent. POST /.shc/launcher/layout answers 405 without contacting the daemon, even with a token obtained before the upgrade. GET and HEAD answer 404. This applies to both panel modes and every app host.

The read-only springboard panel (§30) still reads the user’s arrangement. Arrange in the full console. The legacy grid fallback keeps changes in this origin’s localStorage only and cannot seed or write the daemon’s layout. Where the daemon holds a stored arrangement, every load merges it over the local copy and the stored order wins, so a reorder made in the grid comes back in the stored order after a reload. The dock is the exception: this origin’s shc-dock wins, and the stored dock only seeds a host that has none. The daemon’s self-scoped layout API and stored data remain unchanged.

Sections 25.1–25.9 below record the retired app-host write design. Its same-origin token was readable by any app-page script, so its CSRF ladder could not prevent an app XSS from rewriting the user’s layout. Removing the route, token minting and write relay closes that authority entirely.

“I made a folder with windmill and sonarqube in it and put my tiles in the order I want on cloud.corp. Open the launcher from fleet.corp or idm.corp and it’s gone: back to alphabetical, no folder. I want ONE layout that follows ME.”

25.1 The diagnosis, measured before anything was designed

Section titled “25.1 The diagnosis, measured before anything was designed”

The arrangement lived in localStorage under two flat keys. Measured on the live estate 2026-08-16 by fetching the served page off fleet.corp.bitspur.com and grepping the injected payload:

var T=8*K,HD=500,bd=null,sc=null,nm=null,cur=null,OF=[],KEY='shc-lay';
var MV=0,DX=1,DY=2,KEY='shc-dock',s=btn.style,G=P(16),H=P(26);

localStorage is per origin by specification. Every deployment answers on its own hostname, so every deployment holds its own private copy and no mechanism exists by which one could read another’s. The folder is not lost or racing. It is in cloud.corp.bitspur.com’s storage area and is structurally unreachable from anywhere else. It is not a cookie, so the diagnosis is not the milder “wrong cookie scope” one; there is no scope to widen, and the layout had to leave the browser or the defect could not be fixed at all.

25.2 The identity question, and why it is already answered

Section titled “25.2 The identity question, and why it is already answered”

The obvious fear is that on access: open hosts (17 of the 39 entries in bitspur’s apps.json) forward-auth is not in the request path, so the launcher would have no server-verified identity there and layout sync would only work on gated hosts.

That fear is obsolete. The launcher stopped depending on the gate when it grew its own silent OIDC check (§7): a framed prompt=none authorize, exchanged server-side by the confidential client, leaving the browser an opaque HttpOnly handle. /apps reads that handle, presents the token to the daemon, and the daemon answers with the caller’s own name. That name is already carried into menuIdentity.User and already rendered into the profile block (§23).

The invariant that falls out of it is the clean part:

Layout sync is exactly as available as the launcher itself.

There is no state in which the launcher renders tiles but cannot name the caller; /apps answers 401 with no body to anybody the daemon has not named. So “which hosts get layout sync” is not a new question; it is “which hosts get a launcher”, already asked and already answered.

A shared parent-domain cookie was not taken, for the two reasons §7 already refused design (A): it mints an ambient credential readable on hosts SHC does not control, and it structurally cannot reach hq.flyingfoxlabs.in, which bitspur routes and which is not under .corp.bitspur.com.

25.3 What moved, and what deliberately did not

Section titled “25.3 What moved, and what deliberately did not”
KeyWhere it lives nowWhy
shc-docklocalStorage, per host, unchangedThe reason to move the trigger is that this app’s toolbar is underneath it. §14’s argument survives intact.
shc-layThe daemon, keyed by the user, served to every host, and still written to localStorage as the offline copy and the fail-soft floorA folder named “Ops” is a statement about how this person groups the estate. It is the same statement on every host.

The old design note said the arrangement was “localStorage-only, per host, NO PUT”. That note conflated the two, and the split above is the correction.

25.4 The CSRF ladder: the objection the old design was refused on

Section titled “25.4 The CSRF ladder: the objection the old design was refused on”

The old refusal was right that accepting a mutation under /.shc/launcher/ means designing CSRF for the most widely exposed surface SHC has. What it did not weigh is that the read endpoint beside it is already unreadable cross-origin (/apps sets no Access-Control-Allow-Origin, ever), which is what makes a double-submit token actually secret here.

Four rungs, all required, one byte-identical 401 with no body:

  1. Origin. Present, and its authority equal to this request’s host. Absent is a refusal, not a pass. The scheme is not compared: gateRequestProto defaults to https because Traefik terminates in front, so comparing it would refuse every save on a plain-HTTP router, and an attacker who can answer for this exact host is already past this rung’s reach.
  2. Content-Type: application/json. Not a CORS-simple type, so no form, image or iframe can produce it, and a fetch that tries is held for a preflight this endpoint answers with nothing.
  3. The token. HMAC over the credential fingerprint and the host, minted on /apps, echoed in X-SHC-Layout. No server-side store, it dies with the session, and one host’s token does not verify on another.
  4. The credential. The same ladder /apps climbs.

What rung 3 does not claim. A script running in the page can read the token, because the payload can. That is not closable (a script with that reach can simply drive the launcher’s UI) and the honest bound is that an XSS on somebody’s app buys the ability to rearrange that user’s own tiles. Not read another user’s, not write another user’s, not learn anything about the estate /apps did not already say.

25.5 Whose layout, and what happens on a conflict

Section titled “25.5 Whose layout, and what happens on a conflict”

Whose: their own, and the route cannot express anything else. There is no ?user=, no body field naming a subject and no admin override; the storage key is the authenticated Keycloak sub and nothing the caller can influence. That is stronger than an RBAC check, which is a branch that a later edit can invert. The key is the sub rather than the username so that renaming a user in Keycloak does not orphan their arrangement.

Conflict: a compare-and-set on a monotonic rev, never last-write-wins. A write states the rev it was derived from; a mismatch answers 409 with the current layout in the body, so the loser merges in one round trip instead of re-reading and guessing. There is no force flag.

The retry is exactly one. Two devices both saving in a loop must not become a write storm.

The losing device does not re-render. A save is what a drag ends in, so re-applying a merged layout mid-gesture would yank tiles out from under a finger, a worse defect than a layout that catches up on the next open, which it does, because the next open reads the merged copy off /apps.

25.6 The import: his existing folder is not thrown away

Section titled “25.6 The import: his existing folder is not thrown away”

rev: 0 is the seed write, admitted only when this subject has nothing stored. The first origin whose launcher opens uploads whatever that origin held. Later origins are refused with 409 and merge:

  1. The server copy is authoritative for order.
  2. A folder beats loose placement. A folder the local copy has and the server copy does not is created, and its members are removed from wherever the server had them lying loose.
  3. Anything else the local copy names and the server does not is appended, in local order, to the last page.
  4. Nothing is ever deleted by a merge.

Rule 2 is the one that matters and the reason the merge is ~1,000 bytes rather than ~200. A plain append-only union loses the owner’s folder whenever the origin without the folder syncs first: it finds both members already present, adds nothing, and “Ops” is silently gone. A folder is a deliberate act; a loose tile in the default order is the absence of one, and a deliberate act outranks an absence whichever host happens to sync first.

So the outcome is stateable in one sentence:

Membership and foldering are independent of which origin syncs first; only the position of items neither copy foldered follows first-seen order.

SituationWhat happens
Daemon has no layout route (every estate, until this rolls)/apps carries no lay at all. The payload leaves this origin’s localStorage alone, writes nothing, and renders exactly as it does today.
Store unreachableSame as above. /apps still answers; the launcher still draws.
lay present, rev 0, no arrangementAsked, nothing stored → seed.
Write failslocalStorage was written first and unconditionally, so the arrangement is not lost. The panel is stamped data-shc-saved="0" and carries “Layout not saved: this device only”.

Absent and empty must never be confused. If “could not ask” were read as “nothing stored”, an outage would have every origin seed its own copy and the last to load would win, the accidental last-write-wins the whole design exists to avoid. Both halves of the plugin and the daemon enforce the distinction, and the daemon answers X503931USRLAY rather than an empty layout for exactly this reason.

TreeServed bytes
Before this lane (fixture)30,995
Before this lane (live, fleet.corp.bitspur.com)30,992
After this lane (fixture)33,393

menuPayloadByteCeiling 31,500 → 33,500.

Not one byte of the growth is layout data. The stored arrangement rides the /apps response, which is same-origin, private, no-store and read by nobody but the payload; the glyph sheet and the vendored art already ride there for the same reason. The answer to “fetch it separately rather than raise the ceiling” is that the data already is fetched separately and always was.

What grew is the code: the merge (~1,050), the write with its 409-merge-retry-once and the not-silent failure stamp (~640), the read/seed/import block (~330), and the plumbing (~380). It could have moved out too (shell.go serves JS from /.shc/launcher/shell/<hash>.js) and that was refused on a regression rather than on effort: the injected payload is covered by a CSP hash (§8), a <script src> is not, and moving it out means claiming a script-src on every CSP-strict app on the estate, which is the exact class of app the inline-hash path exists to serve.

The daemon stores one row per subject in the existing generic kv table (namespace launcher.layout, key sub:<keycloak subject>), so there is no migration, no Ent schema and no codegen pass. The value is opaque to the daemon: it does not parse the arrangement, validate that a named tile exists or reorder anything, because the browser half already treats the inventory as authoritative about which apps exist and the layout as authoritative only about where they sit. What the daemon does enforce is a 16 KiB cap, because an unbounded blob on a self-scoping write route is a storage-exhaustion primitive for any account.


26. The free and lapsed launcher: subscribe, and the banner that outlives it (ruled 2026-08-16)

Section titled “26. The free and lapsed launcher: subscribe, and the banner that outlives it (ruled 2026-08-16)”

Owner ruling, verbatim:

“on free shc show the floating menu and when pressed route users through a subscription. Same thing happens when license expires although when license expires it also shows a banner on the website because floating menu is allowed to be disabled it’s just enabled by default.”

Four clauses, and the fourth is the subtle one.

26.1 What free did before this section existed: measured, not assumed

Section titled “26.1 What free did before this section existed: measured, not assumed”

The launcher was free, and it was free by absence rather than by decision: menu.go and launcher.go contained no licence check of any kind, rc.Status was read by neither, and TIERS.md named the launcher in no tier. The only tier question the launcher had ever asked was the profile row’s shc.console.gate (§23.4), which decides one menu row.

So this is a carve-out from free, the second one this product has taken, and it is a larger one than the console’s: the console’s affected population was measured at zero estates, and the launcher’s is every estate that has one.

26.2 The gate: asked, never re-derived, and it is a POSTURE gate

Section titled “26.2 The gate: asked, never re-derived, and it is a POSTURE gate”

shc.launcher.gate (modules/launcher/gate.go), asked by menu_subscribe.go with the caller’s own credential on the same request that already carries a credential to the same daemon.

answerlauncher
200the grid, today’s behaviour, unchanged
403 X403036LICOPTthe subscribe pane in the trial voice
403 X403029LICENTthe subscribe pane in the renewal voice
404, 5xx, a non-licensing 403, a timeoutthe grid

The last row is what makes the roll safe. On the day this ships not one daemon in the fleet carries the route; if 404 read as a refusal, every estate on earth, paid ones included, would swap its grid for a subscribe pitch until its daemon rolled. TestAnUnrolledDaemonRendersThe GridExactlyAsBefore stands between the feature and that outage.

★ The daemon side is a POSTURE gate, not an entitlement key, and that is a finding rather than a shortcut. Entitlements.Bool returns false for an absent key, and Resolver.Allowed reads the held licence’s entitlement map in StateKeyed. Coining launcher as a seventeenth feature key would therefore have refused every licence already minted, every paying estate, on day one, until re-minted and re-activated. That is the rug TIERS.md and modules/license/doc.go promise cannot happen. What the ruling actually distinguishes is posture: free is StateUnlicensed, lapsed is StateDegraded, and paid is everything else, which is exactly “Hobby and above” because no keyed tier sits below Hobby. TestLauncherGateNamesNoEntitlementKey scans the source and fails if that is ever “tidied” into a license.Allowed call.

26.3 What a refused caller is answered: the pane, and no inventory

Section titled “26.3 What a refused caller is answered: the pane, and no inventory”

serveLauncherApps answers 200 with four keys and nothing else: version, state: "subscribe", apps: [], sub. No tiles, no glyphs, no vendored art, no shell reference, no profile. A free estate’s page therefore learns strictly less than it did before this gate existed.

200 rather than 402/403 deliberately: the payload treats every non-200 as “render nothing”, which is right for a refusal it must not paint, and this refusal is the thing to paint.

The gate is asked after the identity ladder, so an anonymous or cross-tenant caller still gets the same silent 401. A subscribe pitch painted for a stranger would be an unauthenticated advert on somebody’s login page, and it would tell the world the estate is unlicensed.

26.4 Where “subscribe” goes: and the honest answer is “not all the way”

Section titled “26.4 Where “subscribe” goes: and the honest answer is “not all the way””

Measured 2026-08-16 by dialling them: the apex and the marketplace answer 200; selfhostedcloud.org/pricing 404s; my.selfhostedcloud.org (the customer portal, the ruled commercial surface) refuses the connection. There is no checkout anywhere.

The estate cannot host one either, and that is a ruling rather than a gap: 2026-08-16-marketplace-identity-and-install.md rules one central store with purchases owned by central accounts, and 2026-08-16-portal-cluster-identity.md rules that the portal federates into a cluster and never the reverse.

So the pane is a pointer, not a checkout, and it points at the two things that exist: the CLI verb (shc license trial start / shc license status), rendered as monospaced text because it is something to type; and one configurable link (appsMenu.subscribeUrl, default the live apex, off for none). What is missing, plainly: there is no self-serve subscribe flow, no plan picker and no checkout. A click lands a human on the vendor’s site.

launcher_enabled, a top-level field of apps.json, absent meaning on, the ruling’s “enabled by default”.

Estate-wide rather than per-deployment, decided rather than defaulted. Per-deployment is already expressible and already spoken for: appsMenu.enabled is ce’s internal plumbing (§8, the SSO-selector middleware turns this injector off on login-page routers and back on for the launcher router), so overloading it would make one switch mean two things and would re-enable the injector where ce deliberately disabled it. The ruling’s own premise (“an operator turned it off”) is one decision about one product. And the daemon is the only side with a config store, which is exactly how envfilter and envprecedence already ride this file.

26.6 ★ The banner is NOT gated on the launcher

Section titled “26.6 ★ The banner is NOT gated on the launcher”

Read the ruling’s dependency the way it is written: the banner exists because the launcher can be turned off. It is the channel that survives the launcher being off, and the operator who disabled the launcher is precisely the one who would otherwise never learn the licence lapsed.

So launcher_enabled: false skips the menu injector and leaves the banner injector alone; they are siblings in one pipeline, appended independently (shcinject.go). The switch deliberately does not live in “whether ce attaches the middleware”, because that would take the banner with it.

Getting this backwards is the single most likely way to ship this ruling wrong, because backwards is also the arrangement that looks tidier: one flag, one feature, off together. TestBannerSurvivesTheLauncherBeing Disabled is the guard, and it asserts both halves on one response: each half is already covered elsewhere and each would stay green under the defect, because the defect is about the two together.

menuPayloadByteCeiling 31,500 → 32,700, measured 32,227 served bytes (31,180 + 1,047). The base was re-measured on main rather than taken from §23.6’s 31,041: four launcher lanes landed in between, and a lane that assumed the older number would have mis-stated its own cost by 139 bytes.

The 1,047 is one payload function (up()) plus three edits under 70 bytes: get()’s wire guard learning that an answer carrying sub and no apps is valid (it previously discarded it, which would have shipped the whole feature as a blank corner), build()’s fork, and skipping dress()/home() on a pane with no tiles to arrange.

No copy rode the payload. All five sentences a refused user reads (heading, paragraph, command, anchor label, URL) arrive at runtime on the private inventory response, exactly as §23.5 requires.

The owner drove his live launcher with a folder open and sent five rulings in one sitting: four about the folder, one about the profile chip. This section is the estate-facing record; the argument for each line lives in traefik/plugin/menu_folders.go and menu_profile.go.

27.1 Drag-out was invisible: a clip, not a z-index

Section titled “27.1 Drag-out was invisible: a clip, not a z-index”

Verbatim: “notice when i drag an icon off the folder it becomes hidden instead of showing on top of the folder.”

Two faults, one symptom, and the second would have bitten the moment the first was fixed:

faultwhy no z-index could have fixed it
the board is overflow-y:autoan overflow scroller clips its children to its padding box, and clipping is not a paint order; a child cannot escape an ancestor’s clip at any z-index
the board is position:absolute; z-index:8that is a stacking context, so the held tile’s z-index:9 was resolved inside an 8 and could never out-paint the rename field (z-index 9, a sibling of the board)

The fix is that the tile leaves the board. lift() reparents the held anchor to the pane on the first millimetre of travel, freezing its on-screen box first, pinning its width, setting H.r0 so the frozen-rect reader does not fall through to a live rect that already carries the drag transform, and re-taking pointer capture, because moving a node between parents removes it from the document for the duration of the move and the spec releases capture implicitly when that happens. gh() then raises it to z-index:12, above the board (8), the rename field (9), the scrim (7) and the header and field (1).

It runs for folder drags only. Lifting a field tile would remove it from the grid, and removing a grid item reflows every tile after it, under a finger, against the rects base() has just frozen.

Measured in Chrome 147 at 390×844 DPR3 with ShadowRoot.elementFromPoint at the dragged tile’s own centre, the browser’s own hit test, through the real paint order:

stepbeforeafter
inside the boardpainted on toppainted on top
straddling the edgepainted on toppainted on top
half outhit test returns the boardpainted on top
fully outhit test returns the boardpainted on top

27.2 Folders are translucent: the deliberate reversal of defect (c)

Section titled “27.2 Folders are translucent: the deliberate reversal of defect (c)”

The owner wants to see the home screen through an open folder. Defect (c) was diagnosed one layer too coarsely: the original bug was a 63%-alpha board over the full-contrast springboard, and the fix that shipped (opaque board, 72% scrim) cured the collision by removing the see-through, which also removed the one cue that says there is a home screen outside this, and you can drop things on it.

Legibility moves to the backdrop, in three layers that degrade in order:

  1. the scrim dims less: rgba(4,8,16,.38), not .72;
  2. the scrim blurs (backdrop-filter, both spellings, one value), so one filter frosts everything behind the whole overlay rather than a second compositing layer on the board;
  3. the board is a light translucent card: a white alpha gradient with the inset hairline mkF()’s folder face already uses, so an open folder reads as the same object as the tile it grew out of.

With no backdrop-filter at all, layers 1 and 3 stand and the springboard shows through unblurred. That is busier than intended and it is still the thing that was asked for.

27.3 More room around the folder: and box-sizing is the margin

Section titled “27.3 More room around the folder: and box-sizing is the margin”

Verbatim: “leave a bit more space around them so there’s more room and more obvious i can drag things off of it.”

The board was left:20 right:20 top:92 bottom:92. On a 390px phone that is 20px of springboard either side, half a fingertip, nothing to drag onto. It is now:

  • width 78%, capped at 430px, centred with left:50% + translateX(-50%). On a phone that is 304px with 43px of home screen either side; on a desktop it is a 430px card, not a 1300px sheet.
  • height its own content, top:120px with max-height: calc(100% - 270px) instead of a bottom. top plus bottom stretches an absolutely positioned box between them, which is how a two-icon folder came out 630px tall on a desktop; the max-height keeps the old floor as a cap and a fuller folder still scrolls inside itself.
  • box-sizing border-box, and that is not decoration. Measured in Chrome at 390×844 before it went in: the declared 82% resolved to a 344px board rather than 320, because the default content-box adds the 12px padding on each side. A geometry ruling whose number is silently 12px off on each side is a geometry ruling nobody can review.

27.4 Drag out and hold closes the folder; the continuity is the feature

Section titled “27.4 Drag out and hold closes the folder; the continuity is the feature”

Verbatim: “when i drag off of it and hold off of it the folder closes and the app can still be dragged where i want on the home screen.”

Anything can close a folder. What the ruling asks for is a folder that closes without the gesture noticing: no cancel, no restart, no snap-back, and the tile still in the air afterwards.

  • the trigger is the held tile’s centre leaving the board, not the pointer’s position, because cont() already decides the drop container from the tile’s centre, so the dwell starts at exactly the moment the drop target stops being the folder.
  • the dwell is 600 ms. iPadOS lands in the 0.5–1 s band. The floor is accident-avoidance: a member carried across the board can leave and re-enter its bounds in a couple of hundred milliseconds, and closing on that would make in-folder reordering impossible near the edges. The ceiling is the ruling itself; a hold you have to wonder about is a hold you abandon. It is deliberately not 500 ms: HD is the press-and-hold that arms a drag, and a second timer sharing that number would invite the two to be read as one gesture.
  • it is armed on transitions only. Crossing out starts it; crossing back in clears it. Moving around outside does not restart it; “hold off of it” is about staying out, not about staying still.
  • the continuity is free, because of §27.1. By the time a dwell can fire, the held tile is a child of the pane: shutF()’s teardown loop cannot remove it, and a node that is never removed never loses its pointer capture. The folder is dismantled underneath a live gesture and the gesture is untouched.
  • shutF() no longer saves while a drag is in flight. The held tile is parented to the pane, so snap() cannot see it, and a save fired by the mid-gesture close would write (and POST to the daemon) an arrangement with that app missing. The release saves unconditionally a moment later.

Measured in Chrome at 390×844 DPR3: folder still open at t+484 ms after the crossing, closed at t+786 ms, the same tile still held and captured through both, dropped at the released slot, and exactly one POST to /.shc/launcher/layout for the whole gesture.

27.5 The profile dropdown is deleted; the chip is a door

Section titled “27.5 The profile dropdown is deleted; the chip is a door”

Verbatim: “i don’t want this dropdown menu on the floating menu. instead clicking the icon should take me straight to the console.”

The sheet, the scrim, the card, the “Signed in as” header, the Account row and the note rows are deleted, not hidden. Every byte of them was delivered to every anonymous visitor on every host of the estate. The chip is an <a href> to launcherProfile.Console, the same URL consoleHref() already resolves (the resolution shc!196 fixed when it stopped resolve’s structural unentitled flag from skipping every console tile), opened target=_blank rel=noopener and closing the panel like every tile.

The edge cases keep their honest answer, which is absence. buildLauncherProfile distinguishes four outcomes and only one ever produced a live href:

the daemon saidthe sheet used to drawthe chip now
entitled, routed, openablea Console linkthe chip
entitled, nothing routed”not deployed on this estate”no chip
licence refused / never licensedthe tier or trial sentenceno chip
unknown, or no rolenothing at allno chip

Keeping the chip and hanging the refusal off it was considered and rejected: with no sheet the only place left for the sentence is a title attribute, which a phone never shows, a pitch nobody can read attached to a door nobody can open. The upgrade journey is not lost with it: an estate that is merely unlicensed keeps its console and estate-settings tiles (applyConsoleAccess removes them only for the ROLE refusal), and §26 owns the pitch those lead to. Account and identity now live in the console’s own top-left avatar menu.

The wire is unchanged on purpose. u, s and cn still ride the private inventory response, which has no byte ceiling, because the console’s own avatar menu is the surface those fields are moving to.

27.5.1 …and the door is the account profile (2026-08-21)

Section titled “27.5.1 …and the door is the account profile (2026-08-21)”

Owner rule, applied to both surfaces at once: clicking the user profile avatar (in the launcher and in the Console) opens the Keycloak account profile, <issuer>/account/. The Console’s half is features/console/src/springboard/AccountButton.tsx, whose avatar menu gained an Account entry at the top; the launcher’s is the chip’s href moving from p.c to p.s.

The shape §27.5 decided is untouched: one anchor, no dropdown, target=_blank rel=noopener, closing the panel like every tile. Only the destination moved, and the Console did not lose a door; it has a tile on the grid with its own long-press menu into its screens (§28).

Why an avatar opens the account console. The chip is a picture of a person. Every other affordance here names a place; the one that names a human opens the human’s own settings (password, MFA, sessions), which is per-user, ungated and present on every estate at every tier. The table above therefore collapses: the chip is rendered exactly when p.s is set, so a licence refusal, an un-deployed console and a silent daemon all keep the identity affordance, and only an unresolvable realm removes it. Absence is still never a guessed hostname.

And the URL is the caller’s own realm, from the daemon. ce publishes account_url on GET /api/user/effective-apps (modules/user/types.go, additive and omitempty, resolved through the AccountURLResolver seam onto auth.Service.AccountConsoleURL, the same issuer the token iss pin enforces). buildLauncherProfile prefers it and falls back to accountURL()’s per-host realm lookup when it is absent.

That preference is a fix, not plumbing: the per-host lookup answers with the realm of the host, which is wrong for anyone whose token came from another one: a platform admin off master browsing tenant corp’s app was pointed at corp’s account console, where they hold no account. The fallback stays wired so an un-rolled daemon keeps the chip it has today, and the preference skips the lookup rather than overriding it.

Verbatim: “on the floating menu you don’t need to put the tenant next to the app names as it only shows from that tenant anyways.”

The one thing this launcher has ever printed next to an app name was a parenthesised environment, appended by renderMenuApps whenever the answered set spanned more than one. His reason applies to it exactly: the surface is single-tenant by construction (§7 refuses any identity whose tenant is not the host’s) and single-environment by his own 2026-08-17 ruling (§20), and dedupeMenuEnvironments already collapses every stack to one tile by precedence, so the suffix annotated a choice the user cannot see, cannot act on and did not make. It is gone, and menuSpansEnvironments with it.

It frees wire bytes twice over on a response fetched once per page view: the suffix itself, and a second copy of most names, because " (staging)" pushes a label past menuCaptionMaxRunes and captionEveryTile then ships the middle-ellipsis form alongside it. It frees zero payload bytes: it is server-side Go, not injected script.

27.7 The defect found on the way: restored folders were dead

Section titled “27.7 The defect found on the way: restored folders were dead”

all() walks the shelf, the pages and the OPEN board. A folder rebuilt by apply() holds its members in F.items, detached (mkF() takes them out of the tree), so at install time no board is open, all() cannot see them, and the arming loop skipped every member of every restored folder. They came back with no pointerdown handler: not draggable inside the folder, not out of it, not onto the field.

It was invisible for a whole session, because a folder you had just made was assembled from tiles gset() had already armed. It appeared on the next page load, which is every page load, for a layout that persists to the daemon on purpose. Reproduced in Chrome against the pre-fix payload: the drag never started at all.

The arming loop now reaches inside the folders. It is done there rather than inside mkF() because mk2() also calls mkF(), with two tiles that are already armed, and gset() wraps A.onclick around whatever was there before, so a second call on the same node would stack two wrappers.

27.8 prefers-reduced-motion, honoured for the first time

Section titled “27.8 prefers-reduced-motion, honoured for the first time”

RM is asked once and gates the only animation this file has: base()’s 165 ms transform transition, which is what makes the neighbours slide during a reorder. Under reduce the neighbours still move, and to exactly the same places; the preview is the FUNCTION, the easing is the MOTION. Nothing the four rulings add animates at all. Measured in Chrome with prefers-reduced-motion: reduce emulated: identical displacement (translate(-91.5px, 0px)), transition transform 0.165s → none 0s.

bytes
before35,888
after35,180
ceiling (unchanged)36,000

The profile dropdown freed 1,764; the folder work, the reduced-motion gate and the arming fix spent about 1,056. The ceiling was not raised.

28. The panel header, as it actually ships (recorded 2026-08-18)

Section titled “28. The panel header, as it actually ships (recorded 2026-08-18)”

§27.5 deleted the profile dropdown and left an identity chip in the panel header. Nine minutes after that landed, a second lane landed the Keycloak Log out control (traefik/plugin/menu_logout.go) into the same header. Neither lane could see the other, so this section records the row they add up to and the two things about it that nothing was holding.

Left to right, and this is the order the code produces rather than a wish:

childbuilt bywhat it is
markbuild()the SHC glyph
”Applications”build()the panel title
identity chipwho(), menu_profile.goan <a href> to the caller’s Keycloak account profile (§27.5.1), _blank/noopener, closing the panel. Present only when the daemon named the caller AND a realm resolved for them.
Log outbye(), menu_logout.goan <a href> to the sidecar’s /.shc/auth/logout on a gated host, or the realm’s end-session URL on an ungated one. Present only when the host has a logout route.
close Xbuild()last child, by contract

Both optional controls insertBefore(close), so their relative order is decided by nothing more durable than the order build() calls them in, and the close X stays last only because neither appends. The chip is a door and belongs near the title; Log out is the only control in the panel that destroys anything and belongs beside the way out.

Measured in Chrome 147 at 390x844 DPR3 against the served bytes, with a wire carrying both me and o: chip at x=187..223, “Log out” at 235..316, close at 328..372, in a 390px header whose own margin is 18px. They fit, in that order, on the narrowest phone the launcher targets.

Every existing header assertion was true of a header with exactly one of the two controls in it, because each lane’s fixture omitted the other lane’s field; logoutInventory carries no me, inventoryWith carries no o. “My parent is the header” and “close is last” both survive a build where the chip vanishes the moment a host has a logout route.

TestTheHeaderCarriesBothTheIdentityChipAndTheLogoutControl (menu_logout_node_test.go) renders both from one inventory and holds four claims: both present, neither armed by the tile drag machinery, chip-then-logout-then-close, and the chip’s href still the account console. Proved by mutation: swapping build()’s call order, suppressing the chip when D.o is set, blanking the chip’s href beside a logout control, and arming the chip beside one each fail this test and no other test in the package.

§27.9 recorded 35,180 bytes. That was the truth of its own merge and stopped being the truth of main nine minutes later, when the logout control landed on top of it.

bytes
before §2735,888
after §27 (the folder work and the deleted dropdown)35,180
after the Log out control35,505
ceiling (never raised)36,000

Headroom on main is 495 bytes, not the 820 §27.9 implies. Anyone spending against this budget should read this table, not that one. This section costs zero payload bytes: it is documentation and a test.

29. The unreachable tile: greying what this network cannot open (built 2026-08-18)

Section titled “29. The unreachable tile: greying what this network cannot open (built 2026-08-18)”

The owner’s question, verbatim:

“if an app is not public and i access another public app and open the floating menu will the public app show up greyed out? or if i’m in the console not from lan will it show those apps grayed out?”

The measured answer before this section was written was NO, on both surfaces. renderMenuApps carried no exposure or reachability concept, and the console’s springboard had no disabled state. Every entitled app listed identically whether or not the viewer could reach it, and clicking an unreachable one produced a bare 403 from the ipAllowList middleware with nothing to explain it. This section is the build.

29.1 ★★ It is presentation. The middleware is the boundary.

Section titled “29.1 ★★ It is presentation. The middleware is the boundary.”

Say this first because it is the thing most likely to be forgotten by whoever edits this next.

The enforcement is, and stays, the per-deployment ipAllowList middleware ce/modules/app/lan_allowlist.go renders in front of a restricted deployment’s routers. Nothing in this section grants or withholds access:

  • a greyed tile is still listed, still focusable, still openable, and is refused by the middleware if the viewer is outside the ranges;
  • an un-greyed tile is refused by that same middleware under exactly the same rule. Absence of the mark is not permission.

Both code paths carry that paragraph at their top (traefik/plugin/menu_reach.go, modules/console/reach.go) precisely where a future reader would be tempted to move a check into them.

29.2 The mechanism differs per surface, and that is the crux

Section titled “29.2 The mechanism differs per surface, and that is the crux”
LauncherConsole
Where the code runsinside Traefik (yaegi)a browser app + the daemon
Who the peer isr.RemoteAddr is the browserr.RemoteAddr is Traefik
Reads a forwarded headerneveryes; see §29.4

The launcher is nearly free. The plugin is a Traefik middleware, so the request it answers arrived on the same TCP connection ipAllowList judges, and LanAllowlistMiddleware declares no ipStrategy precisely so that it reads the real peer rather than a client-sent header. The plugin therefore re-decides a decision being made beside it, from the same input.

The answer transfers across routers: the peer is a property of the connection, not of the hostname it asked for, so “would that app’s allowlist admit me” is answerable from the page the viewer happens to be standing on.

Measured against the live estate, 2026-08-18: bitspur/hel1 has the knob armed for one deployment:

ProbeResult
the restricted host, from outside the estate403
…+ X-Forwarded-For: <an admitted node address>403
…+ X-Real-Ip: <an admitted node address>403
the same host, from a node on the admitted plane401
an exposure: internet host, from outside200

The two spoofed 403s are the whole point: the deployed middleware reads the connection, not the header. The 401 is the forward-auth gate answering, which means the packet arrived, so the allowlist admitted it. And a middleware that judges the true peer can only do so because Traefik hands its middlewares the real RemoteAddr, which is exactly the input the plugin reads.

apps.json grows two additive fields (no version bump; the file’s contract is that new needs are met by adding fields):

FieldWhereMeaning
lantop levelthe table of distinct enforced source-range sets, in first-use order
lansetper entry1-based index into lan; absent/0 means no restriction is rendered

A table rather than a list per entry, and the reason is measured: bitspur/hel1 derives 44 CIDRs for its one armed deployment and its apps.json is 10,427 bytes for 54 entries. Copying the set onto every entry would cost ~700 bytes each (a ~38 KB file on an estate that armed the knob tenant-wide, rewritten and diffed by the 60 s sweep) to say one thing 54 times. Two deployments genuinely can derive different sets (lanAllowlistCidrs is scoped), so the table holds each distinct set and no entry is ever pointed at a set that is not its own.

The daemon stamps this from LanAllowlistFor (the same function the ingress reconcile calls to decide what the middleware enforces) on the same node, in the same sweep. The published ranges and the enforced ranges cannot drift because they are one call.

This is the same publish-the-policy / evaluate-the-viewer split that envfilter and envprecedence already ride (§12.7): one apps.json serves every viewer of every host, so anything per-viewer must be evaluated by the side that holds the request.

29.4 The console: three honest options, and which was chosen

Section titled “29.4 The console: three honest options, and which was chosen”

The console is a client-side app over an API, so it does not inherently know what its browser’s network can reach.

OptionVerdict
(a)The daemon computes it from the request’s source address and stamps it on an inventory responseChosen
(b)The console probes each hostRejected
(c)No mark; explain the refusal when it happensKept as the fallback

(b) is rejected on mechanics, not taste. A cross-origin fetch to a host the browser cannot reach does not fail fast (it hangs to a TCP timeout) and CORS makes success and failure indistinguishable from script anyway. It would also fire a real request at every app on the estate on every home-screen paint.

(a) carries a caveat that had to be measured. MEASURED on bitspur/hel1 2026-08-18: the console is served through Traefik; https://shc.hel1.hetzner.bitspur.com/ answers 200 on port 443 carrying x-shc-ratelimit: on, the daemon’s own header. So r.RemoteAddr at the daemon is a docker-bridge address belonging to Traefik, which is itself inside every derived allowlist. Answering from RemoteAddr alone would tell every console viewer that everything is reachable, a constant wearing a feature’s clothes.

shc.console.reach therefore reads X-Forwarded-For, which LanAllowlistMiddleware explicitly refuses to do. The two are not in conflict, because they answer different questions:

  • the middleware is a control; a spoofable input there is an allowlist walkable from the open internet, so it must never read a header, and it does not;
  • this route is a picture; the worst a spoofed value achieves is a wrong picture, for the spoofer, on their own screen. It cannot move what Traefik does, and the answer is computed per request and returned to that request alone, so it cannot reach another viewer.

A claim that stood here was false, and is recorded rather than quietly deleted. This section asserted that a browser cannot set X-Forwarded-For because it is a forbidden header name. It is not on the Fetch spec’s forbidden list. Measured in Chrome against a header-echo server, 2026-08-18: both fetch(url, {headers: {'X-Forwarded-For': '10.236.16.9'}}) and xhr.setRequestHeader('X-Forwarded-For', …) arrived at the server verbatim. The design survives (the two reasons above never depended on it), but an argument nobody checked is exactly how a real control ends up resting on one. What the spoof does buy is an oracle; see §29.8.

The header is believable on the deployed path because Traefik’s websecure entrypoint declares no forwardedHeaders.trustedIPs: it discards whatever the client sent and writes the observed peer itself. The route reads the rightmost value for the general case (the only entry in a chain a client could not have written) and falls back to RemoteAddr when no header is present (a desktop shell talking straight to the daemon).

(c) is the fallback rather than the design. When the viewer’s address cannot be established the route answers known:false and the console marks nothing, which is exactly (c).

Every failure path renders the tile normally:

  • no lan table (a daemon that predates the field);
  • an entry with no lanset (unrestricted, or underivable at the daemon; LanAllowlistFor returning an error publishes nothing);
  • a lanset pointing outside the table (a torn or hand-edited file);
  • a peer address that will not parse;
  • a set whose ranges will not parse.

The asymmetry is deliberate. A false grey is a working app the product told the user not to click. It costs a user their app and teaches them the menu lies. A missing grey costs one click and a 403, which is precisely what every estate did before this shipped. The console’s wire keeps known as a separate field for the same reason: “I checked and everything is reachable” and “I could not check” are different sentences, and an empty list only says the first.

Two channels ship on both surfaces, and neither is the label:

  1. grayscale(1) on the artwork, the thing a person recognises a tile by.
  2. .45 opacity on the picture (the launcher’s glyph node; the console’s glyph box).

The second channel exists because of what the first one missed. Driven in a browser at 390×844 DPR3: grayscale alone left paperless byte-identical to its reachable self (it ships a white feather) while gitlab’s orange fox went obviously grey. One signal that a particular icon defeats is no signal.

The caption is untouched. It is the only thing on a tile with a contrast requirement, it sits on a wallpaper that is dark in both themes (the launcher paints its own surface; see packages/springboard-ui/src/wallpaper.ts), and dimming it to say something about the network would trade legibility for a signal the icon already carries. No animation is involved, so prefers-reduced-motion is unaffected.

A third channel was tried and removed. A dashed border was written, shipped into a browser, and measured as border: none 0px on every tile: dress()/home() re-style the anchor’s box when they lay the home screen out, so the anchor’s own border never survives to paint. It was deleted rather than left in as bytes that look like a feature.

A11y: the reason is in the accessible name, not only in the colour. Both surfaces append , not reachable from this network to the tile’s aria-label (and title on the launcher), beside the verb. aria-disabled is deliberately not set: the tile is not disabled, it is unreachable, and activating it is how a user learns what the boundary says.

A tile’s right-click / long-press menu (k, sidecar stacks and vapp instances) is not marked. It is a scope line, not an oversight, and it degrades the safe way: an unmarked kid is a missing grey, exactly the behaviour every estate had before this shipped. The bytes are the scarce thing (a kid mark needs a wire field, a fold-time copy of the parent’s lanset, and a branch in the compact arm() that paints the menu), and a sidecar folds onto its parent precisely because it belongs to the same app; the common shape is one exposure for the pair, and the parent tile already carries the mark. menu_reach.go records how to build it if it is ever wanted.

menuPayloadByteCeiling is 36,000 and was not raised.

Served payload bytes
Before35,505
After35,623
Cost+118
Headroom remaining377

The wire cost is a single omitempty flag character (x) per marked tile, and the launcher’s /apps response is same-origin, private and no-store, so it is not what the ceiling bounds in any case. The response carries the boolean only: never the ranges it was computed from, which are the estate’s internal topology. TestReachMarkNeverShipsTheRangesItWasComputedFrom holds that.

29.8 ★ The disclosure note, for the owner to rule on

Section titled “29.8 ★ The disclosure note, for the owner to rule on”

Greying tells a viewer exactly which hosts are private.

The honest assessment is that this is a small leak, because the same viewer can already derive the same fact by clicking: a reachable host answers, an unreachable one answers 403. The mark converts an n-click enumeration into a single glance, for a viewer who is already authenticated, already entitled to the app, and already being shown its name and hostname in the same menu.

It is recorded here rather than decided here. If the owner would rather the launcher said nothing, the smallest reversal is to stop stamping lanset in BuildAppsMenu; every reader already treats its absence as “nothing is restricted”, so the marks disappear estate-wide with one config-free change and no image roll.

The second disclosure is an oracle, and it is the console’s alone. Because shc.console.reach believes X-Forwarded-For (§29.4) and a browser really can set it (measured, above), a caller who already holds the console’s Ops role can ask “would 10.236.16.9 be admitted?” by sending it and reading which stacks come back, and so map the estate’s admitted ranges without shc config get lanAllowlistCidrs.

Bounded, but real:

  • the caller is authenticated and already entitled to the console (AccessFor(r).Ops, the read-only support floor);
  • the ranges are the estate’s own private networks and node addresses, not a secret; the same operator can read lanAllowlistCidrs through the config API;
  • the answer is never readable cross-origin: the daemon sets no CORS headers at all (ce/core/api/server.go, by design), so a hostile page cannot run this probe on a logged-in operator’s behalf;
  • it moves nothing. The ipAllowList middleware is unaffected by any of it.

If you would rather close it, the route can read RemoteAddr only, at the cost of the entire console half, which then marks nothing on any estate that serves its console through Traefik, which is every estate measured so far.

30. The springboard panel: read-only and server-rendered (ruled 2026-10-30, FZ-8492)

Section titled “30. The springboard panel: read-only and server-rendered (ruled 2026-10-30, FZ-8492)”

The owner’s ruling: the floating panel on an app page is a read-only copy of the console’s springboard. It looks like the springboard, it opens apps and nothing else, and one link opens the full console in its own tab. It ships no MPO bundle and no React. It sits behind launcher.panel until it has run on corp.

The Traefik plugin renders it at request time from templates a build step generates out of the console’s own components. The plugin already proves the caller and builds the per-user tile list for /apps, so the panel is the same inventory written as a tree instead of JSON. Nothing new learns the launcher handle, and there is no extra hop to the daemon.

make gen-launcher-panel runs packages/springboard-ui/src/launcherPanel.spec.tsx, which server-renders LauncherPanel (the springboard’s Wallpaper, StatusBar, SpringboardField, StackTile, ConsoleAppTile and Dock under the console’s Tamagui config) at every width the springboard’s media queries distinguish, in dark and light. It then:

  • keeps the Tamagui and react-native-web rules the tree uses, rescoped from :root to :host;
  • turns every inline style into a generated class, so no style attribute reaches the page;
  • folds the width and scheme variants into @media overrides, and fails if a variant changes the tree’s shape;
  • cuts Latin subsets of the console’s Inter 400 and 700;
  • writes traefik/plugin/panel_gen.go: the shell, the tile and dock templates, the CSS, the fonts and the monogram fixture.

A stale panel_gen.go fails that spec. The monograms and hues are a Go port of resolveMarks, checked against the whole catalogue (TestPanelMarksMatchTheConsole). The stored layout orders the field and the dock the way the console does. A folder’s apps take the folder’s place in the field, one tile each; the panel draws no folder tile yet.

This widens the reserved /.shc/launcher/ set by two paths.

pathanswers
GET/HEAD /.shc/launcher/panelthe panel as a JSON element tree, private, no-store, gzip when asked. Same credential ladder and the same byte-identical 401 as /apps; the subscribe and grantless answers and an unarmed tenant get that 401 too.
GET /.shc/launcher/panel/<sha256 prefix>.{css,woff2}the stylesheet and the two font subsets, content-addressed, public, max-age=31536000, immutable, no identity.

The tree carries the tenant name and, per tile, the name, caption, link, icon and monogram. It carries no profile, logout link, layout token, handle or token (TestPanelAnswersOnlyTheAppList). Every other method is 405.

“Open console” links to the tenant’s console route, read before the console role gate, so a caller below tenant:read gets the link too; the console decides what that caller sees. Only a tenant with no console route gets an empty link, and the panel CSS hides an empty link (TestPanelOpenConsoleShowsWhateverTheCallersConsoleRole, FZ-9214).

/apps answers pn: 1 when the host’s tenant has launcher.panel: springboard. A press, or a hover, focus or touch on the trigger before it, fetches /panel, the CSS and both fonts in parallel. The loader adopts the CSS as a constructed stylesheet on the launcher’s shadow root, registers the fonts with FontFace from an ArrayBuffer (Chrome ignores @font-face inside a shadow root, and a buffer is not a font-src load), and builds the tree with createElement, so a Trusted Types page doesn’t throw. It sets the date and time, focuses close, and puts a tile’s monogram back if its icon fails. A tile or the console link closes the panel as the new tab opens. A non-200, a missing CSSStyleSheet or a 4 s timeout drops to the drawn grid, as before.

launcher.panel is menu (the shipped default, the drawn grid) or springboard, global or tenant scope, live. The daemon stamps the resolved value as panel on each of the tenant’s apps.json entries.

shc config set launcher.panel springboard -t corp --scope tenant

Rollout: corp first, then the other tenants, then the global default. FZ-8531 retires /layout and its write token after Ogden’s global switch to springboard on 2026-11-03. Retiring the drawn grid, the shell slot (§18-19) and the knob remains separate work.

Served payload bytes
Before39,444
After41,962
Cost+2,518
Ceiling42,022

The cost is the JSON-to-DOM builder, the loader with its font and icon handling, the clock, the three asset names and the prefetch. It comes back with about 25 KB more when the drawn grid retires.