@teamscala/service-boot 0.23.319 → 0.23.321

package/src/register-ws-routes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Registers each `service_install.websocket_routes[]` entry as a Hono WS route.
+ * The ORPC WS (`/api/rpc/ws`) is mounted by the canonical primitive
+ * `mountOrpcWs` (@teamscala/orpc/ws/server) over the FULLY-COMPOSED app router —
+ * this runs AFTER registerFnRouters, so the eager RPCHandler snapshots every
+ * namespace, and any `output: eventIterator(...)` procedure dispatches (rule
+ * `orpc-ws-via-mount-orpc-ws`). It is NOT a server_package WsRouteHandler — it
+ * is exempt from the legacy invariant below.
+ *
+ * The legacy `WsRouteHandler` interface (open/message/close on a Bun
+ * ServerWebSocket) is preserved by an adapter for already-migrated
+ * server_packages (terminal-ws); new WS handlers should use Hono's WSEvents
+ * directly.
+ *
+ * INVARIANT (legacy paths only): every handler registered via
+ * mountCtx.registerWsRoute MUST have a matching entry in config.websocket_routes
+ * (minus /api/rpc/ws), and vice versa. A mismatch is fatal — the service cannot
+ * boot with handlers declared but never wired (silent 404 on upgrade), or routes
+ * that point at handlers no server_package registered.
+ */
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
+import type { Hono } from "hono";
+export declare function registerWsRoutes(app: Hono, config: ServiceInstallConfig, mountRegistry: MountRegistry, serviceSlug: string): Promise<number>;

package/src/resolve-app-base-url.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The scala-projects app's own public hostname, read from its `service_install`
+ * row rather than hardcoded — a service knows its own deploy config only
+ * through the registry (registries-are-source-of-truth), never a literal in
+ * source. Cached for the process lifetime: this changes only on a redeploy,
+ * not per-request. Shared by every server-side path that builds a link back
+ * into the app (approval emails, mention emails, digest emails).
+ */
+export declare function resolveAppBaseUrl(): Promise<string>;

package/src/resolve-brand-favicon.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Host-level brand favicon resolution. A single-brand UI service's host has
+ * a KNOWN owner (`service_install.config.brand_org`) — serving the generic
+ * platform "S" at the implicit /favicon.ico path there is a defect: browsers
+ * and crawlers hit that path directly and their favicon caches are sticky
+ * (operator-observed 2026-06-05 on launcha's proposal pages).
+ *
+ * Resolution is by convention from the org's asset store:
+ * `<brand_org>/logos/favicon.png`. Existence is probed once through the
+ * in-process asset proxy and cached (positive AND negative) so the favicon
+ * route never adds S3 latency per request. No brand_org, or no asset at the
+ * convention key → null, and the caller serves the generic fallback.
+ */
+export declare function resolveBrandFaviconPath(brandOrg: string | undefined): Promise<string | null>;
+/**
+ * Eagerly resolve + cache the favicon at boot so the FIRST user request never
+ * pays the S3 existence-probe latency. The probe (`handleAssetProxy` →
+ * `s3.file(key).stat()`) is a COLD S3 call — the connection setup to the asset
+ * store takes 6s locally / up to 21s in prod, and the in-process cache resets
+ * on every restart (deploys, package-poller). Without warming, the first
+ * /favicon.ico after each restart stalls for that duration (operator-reported
+ * 23s). Fire-and-forget — runs in the background during boot, never blocks.
+ */
+export declare function warmBrandFaviconCache(brandOrg: string | undefined): void;

package/src/resolve-brand-favicon.ts

@@ -55,7 +55,7 @@ export async function resolveBrandFaviconPath(
  * pays the S3 existence-probe latency. The probe (`handleAssetProxy` →
  * `s3.file(key).stat()`) is a COLD S3 call — the connection setup to the asset
  * store takes 6s locally / up to 21s in prod, and the in-process cache resets
- * on every restart (deploys, dep-sync). Without warming, the first
+ * on every restart (deploys, package-poller). Without warming, the first
  * /favicon.ico after each restart stalls for that duration (operator-reported
  * 23s). Fire-and-forget — runs in the background during boot, never blocks.
  */

package/src/resolve-from-loader-config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Walks a resource_loader.sources[] graph and resolves each source in
+ * dependency order. Returns an assembled data object keyed by source key.
+ *
+ * Source types: "orpc", "prisma", "resolver_fn".
+ * Each source may declare depends_on for ordering.
+ * Params are interpolated from URL params and prior resolved data.
+ */
+interface SourceConfig {
+    key: string;
+    source: "orpc" | "prisma" | "resolver_fn";
+    model?: string;
+    where?: Record<string, unknown>;
+    select?: string[];
+    depends_on?: string[];
+    optional?: boolean;
+    resolver_fn?: string;
+    resolver_input?: Record<string, unknown>;
+    registry_filter?: Record<string, unknown>;
+    transforms?: string[];
+}
+interface LoaderConfig {
+    sources: SourceConfig[];
+    merge_strategy?: Record<string, unknown>;
+}
+export declare function resolveFromLoaderConfig(config: LoaderConfig, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function interpolateMeta(template: Record<string, unknown>, data: Record<string, unknown>): Record<string, unknown>;
+export {};

package/src/resolve-service-context.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Resolves the minimum service context the bin needs to choose its launch
+ * path: connect DB, load registry, read service_install row, return kind +
+ * port. Caller is responsible for disconnecting.
+ */
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+export interface ServiceContext {
+    kind: "ui" | "backend" | "runtime";
+    port: number;
+    config: ServiceInstallConfig;
+    disconnect: () => Promise<void>;
+}
+export declare function resolveServiceContext(serviceSlug: string, databaseUrl: string): Promise<ServiceContext>;

package/src/resolve-service-port.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @system service-runtime
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Decides which port a service binds, from the two sources that can claim one:
+ * the PORT environment variable and the port the registry declares for that
+ * service (`service_routing.local_port` for a backend, `service_install.port`
+ * for a UI service).
+ *
+ * This is the resolver for BOTH kinds. It lives in service-boot rather than
+ * service-runtime because the UI branch boots from here and may not import
+ * upward; keeping one copy is the point, since the second copy is exactly what
+ * went wrong (below).
+ *
+ * The rule, and why it is not "env always wins":
+ *
+ * Railway injects PORT and healthchecks that exact port, reporting the service
+ * unavailable if it listens elsewhere. So on Railway the injected PORT is
+ * authoritative period — a `service_install`/`service_routing` row carries the
+ * service's LOCAL dev port (e.g. portal 5200), and on Railway binding that
+ * instead of PORT means Railway probes a port nothing listens on and the deploy
+ * fails healthcheck. The registry-wins rule below exists to stop LOCAL port
+ * collisions (one host, many services); inside a Railway container there are no
+ * sibling services to collide with, so PORT must win. `isRailway` is the caller's
+ * assertion that it is booting inside Railway (from `RAILWAY_ENVIRONMENT`).
+ *
+ * Off Railway, a `service_routing`/`service_install` row means this service has
+ * a DECLARED port on this host. There, a PORT that disagrees is a polluted launcher environment, never
+ * an intention, and obeying it binds someone else's port. That is not a
+ * hypothetical: mcp-ai-chat-system booted onto 3021 — session-picker's port —
+ * while its own MCP_SERVER_URL still pointed at 8080. Both processes bound 3021,
+ * SO_REUSEPORT load-balanced between them, and every symptom appeared somewhere
+ * else: a chat loopback that resolved to nothing, tool-description curation
+ * failing for every tool and disabling itself via its circuit breaker, RPC calls
+ * landing in the wrong service, and 59 restarts. Nothing failed loudly because
+ * nothing ever compared the two numbers.
+ *
+ * So the registry wins wherever it has an opinion, and the disagreement is
+ * REPORTED rather than silently resolved — a wrong port that boots cleanly is
+ * the expensive shape, because the damage surfaces far from the cause.
+ *
+ * That reasoning was written for the backend branch and wired only there, so
+ * the UI branch kept taking `process.env.PORT` unconditionally — and on
+ * 2026-07-31 reproduced the identical incident in the other direction:
+ * scala-quiz (kind:ui, declared 5203) inherited a leaked PORT=3021 from the
+ * tmux server environment and bound session-picker's port. Half of every RPC
+ * to the session daemon was answered by a quiz service with no /rpc routes.
+ *
+ * A rule enforced on one of two branches is not enforced. Both branches now
+ * call this function, and `port-resolution-is-registry-authoritative` fails
+ * the push if either stops.
+ */
+export interface PortResolution {
+    /** The port to bind. */
+    port: number;
+    /** Which source decided it — for the boot log, so the choice is auditable. */
+    source: "env" | "service_routing";
+    /** Set when PORT disagreed with the row; the caller logs it. */
+    conflict?: {
+        envPort: number;
+        declaredPort: number;
+    };
+}
+/**
+ * @param envPort   parsed PORT env, or undefined when unset/unparseable
+ * @param declaredPort `service_routing.local_port`, or undefined when the
+ *                     service has no routing row (the Railway-only case)
+ * @param isRailway  true when booting inside Railway (caller derives from
+ *                   `RAILWAY_ENVIRONMENT`); there the injected PORT is authoritative
+ *                   regardless of the row, because Railway healthchecks it
+ */
+export declare function resolveServicePort(envPort: number | undefined, declaredPort: number | undefined, isRailway?: boolean): PortResolution | {
+    error: "no-port-source";
+};

package/src/resolve-theme-mode.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The ONE theme-mode decider for every page render, across every UI app
+ * (portal, proposals, sign, forms, quiz, gpt, public). Every route handler in service-boot
+ * resolves light/dark through this single function — never its own inline
+ * `(... === "dark" ? "dark" : "light")` chain. That inline form was duplicated
+ * across every route branch, so flipping one app's theme required editing
+ * every copy (the heavy lifting this removes).
+ *
+ * Resolution order (first match wins):
+ *   1. ?theme=light|dark on the URL — the embed override. Set when a page is
+ *      framed inside another shell (a form in a GPT tool panel) so the framed
+ *      page matches the host's scheme. Also marks the render `embedded` so the
+ *      page can drop its own brand page-surface and render the host's clean
+ *      surface.
+ *   2. candidates[] — page rootProps.theme, brand theme, website default, in
+ *      whatever priority the caller passes them.
+ *   3. "light".
+ *
+ * Pairs with the brand/token decider (resolveBrand → computeThemeVars,
+ * `unified-brand-theme`): that owns the SURFACE, this owns the MODE.
+ */
+export interface ResolvedThemeMode {
+    theme: "light" | "dark";
+    /** True iff the mode came from the ?theme= embed override. */
+    embedded: boolean;
+}
+export declare function resolveThemeMode(opts: {
+    /** Request URL (or its href) — read for the ?theme= embed override. */
+    url?: URL | string | null;
+    /**
+     * Explicit embed override, when the caller already extracted ?theme= from
+     * the URL upstream (e.g. a pure data-shaper that has no Request). Same
+     * effect and priority as the URL form.
+     */
+    override?: unknown;
+    /** Theme candidates in priority order: rootTheme, brandTheme, websiteTheme. */
+    candidates?: Array<unknown>;
+}): ResolvedThemeMode;

package/src/resolvers/fetch-org-brand.d.ts

@@ -0,0 +1,2 @@
+import type { ResolverArgs } from "./portal-route-paths.ts";
+export declare function fetchOrgBrandWithFallback({ input, client }: ResolverArgs): Promise<unknown>;

package/src/resolvers/portal-route-paths.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * portal-route-paths.ts — pure path mapper for portal region routing.
+ *
+ * Extracted from resolve-from-loader-config.ts (the hardcoded
+ * `resolvePortalRoutePaths` arm) so it can be invoked via a resolver_fn
+ * registry row instead of an if-chain. Faithful extraction — no logic change.
+ * The request path is the center page's builda path ("/" falls back to
+ * home_path), and the per-route toolbar page follows the flat naming convention
+ * `/<last-segment>-toolbar`. Pages without a matching toolbar page simply
+ * resolve an empty toolbar region (the source is declared optional).
+ */
+export interface ResolverArgs {
+    input: Record<string, unknown>;
+    client: unknown;
+    params: Record<string, unknown>;
+}
+/**
+ * Extract the organisation id from a portal-shaped callback/path — the single
+ * authority for "which segment is the org" so the sign-in brand resolver and the
+ * route resolver cannot drift on the answer (portal-branding-resolves-page-org-first).
+ *
+ * The canonical portal shape is `/<websiteId>/<orgId>/<path>` — the org is
+ * segment 1, NOT segment 0. Reading segment 0 fed the WEBSITE id into brand
+ * resolution, which resolved no org and fell back to the super-admin org — the
+ * exact cross-tenant mis-branding this exists to prevent (bind-page-handler.ts,
+ * found 2026-07-21).
+ *
+ * Single-UUID hosts keep segment 0 unchanged: scala-projects routes `/<orgId>/…`
+ * and proposal/form/quiz hosts route `/<resourceId>/…` (a non-org first segment
+ * that resolves to no brand and falls back as before — no regression, only the
+ * correct-org improvement for the two-UUID portal shape). Returns undefined when
+ * neither leading segment is a UUID.
+ */
+export declare function extractOrgIdFromCallbackPath(callbackUrl: string): string | undefined;
+export declare function resolvePortalRoutePaths({ input, params }: ResolverArgs): Record<string, unknown>;

package/src/resolvers/website-by-host-map.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * website-by-host-map.ts — resolves the website + body path for a host.
+ *
+ * Extracted from resolve-from-loader-config.ts (the hardcoded
+ * `resolveWebsiteByHostMap` arm). Faithful extraction — no logic change.
+ */
+import type { ResolverArgs } from "./portal-route-paths.ts";
+export declare function resolveWebsiteByHostMap({ input, client, params }: ResolverArgs): Promise<Record<string, unknown> | null>;

package/src/resource-chat-inject.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Injects the generic ResourceChatLauncher block into an AUTHORISED resource
+ * page (proposal, agreement, or any gated document) — called from a gate's
+ * onAuthorized, so the floating GPT bubble lives strictly behind the email gate
+ * and every resource of that type gets it with no per-page Puck edit. It builds
+ * the resource's page content into a runtime-context string and passes it to the
+ * launcher, which forwards it to the chat as <runtime_context> — so ONE shared
+ * assistant agent answers about whichever resource is being viewed.
+ *
+ * RESOURCE-AGNOSTIC by design (one-ai-chat-system / chat-ui-is-one-canonical-block):
+ * the launcher, the chat engine, and this injector are generic; only the
+ * per-resource CONFIG differs (which agent, the copy, which resolved key holds
+ * the record). The agent id is config, not code (registries-are-source-of-truth):
+ * each resource type names a `config / <slug>-assistant-agent` row carrying
+ * { agentId }. No row (or no agent) → no injection, page renders unchanged
+ * (fail-soft).
+ */
+/** Per-resource-type injection config — the only thing that varies. */
+export interface ResourceChatOptions {
+    /** Key in `resolved` holding the record (e.g. "proposal", "agreement"). */
+    resourceKey: string;
+    /** `config` row slug carrying { agentId } (e.g. "agreement-assistant-agent"). */
+    agentConfigSlug: string;
+    /** Org id to scope the chat. If omitted, read from resolved[resourceKey].organisation_id
+     *  (proposals); agreements pass it explicitly (org isn't on the resolved record). */
+    organisationId?: string;
+    /** Overlay title-bar label (e.g. "Agreement Assistant"). */
+    title: string;
+    /** Floating button label / speech bubble (e.g. "Ask about this agreement"). */
+    launchLabel: string;
+    /** First assistant message. */
+    welcomeMessage?: string;
+    /** Input placeholder. */
+    placeholder?: string;
+    /** Suggested starter questions. */
+    conversationStarters?: string[];
+}
+/**
+ * Inject the generic ResourceChatLauncher behind the gate. `opts` is the only
+ * per-resource-type variation; everything else is shared.
+ */
+export declare function injectResourceChatLauncher(resolved: Record<string, unknown>, viewerEmail: string, opts: ResourceChatOptions): Promise<void>;

package/src/resource-not-found.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ * @indivisible-unit
+ *
+ * One cohesive unit — the branded resource-not-found / holding page: the
+ * PrimaryResourceMissingError trigger, the org-logo resolver the page
+ * renders, and the HTML builder are tightly coupled (the builder consumes
+ * the logo; the error drives the page) and cannot be split without churn.
+ *
+ * Branded 404 for registry page routes whose PRIMARY resource is missing.
+ *
+ * A route that declares `resource_type` (proposal, form, quiz, agreement…)
+ * is meaningless without that entity. Before this existed, a dead link
+ * (wrong id, deleted row) fell through the loader with nulls and rendered
+ * whatever default content the shell could scrape together — leaking
+ * internal pages (the "Vision Toolbar" incident, operator-observed
+ * 2026-06-05) on the org's own branded host, with a 200 status that
+ * search engines and link unfurlers would happily cache.
+ *
+ * The replacement: loadData throws PrimaryResourceMissingError; the page
+ * binder maps it to a minimal branded 404 — correct status, noindex, the
+ * host's own favicon (which resolves the owning org per brand_org), and a
+ * plain human sentence. Deliberately NOT a puck page: the error surface
+ * must render even when data loading is the thing that failed. A
+ * website-editable /404 puck page can layer on top later; this is the
+ * floor that must always exist.
+ */
+/**
+ * The host org's LOGO (wordmark) for the dark error page — the favicon is a
+ * tab glyph, the wrong asset at page scale (operator-observed: a lone "h"
+ * where the launcha wordmark belonged). Resolution: the service's own
+ * install row names its owner (brand_org); the org's dark-theme logo (a
+ * light-coloured mark, correct on the dark page) is preferred, light-theme
+ * second. Every step skew-tolerant: any miss → null → the builder renders a
+ * logo-less dark page.
+ *
+ * Returns the logo as an INLINE data URI (not a `/api/assets/` proxy URL) so
+ * the branded holding/error page ships the logo IN the initial HTML bytes —
+ * no second fetch, no post-paint pop-in, no dependency on the asset proxy the
+ * degraded service is failing to serve (incident 2026-07-27: the logo on a
+ * DEGRADED render-layer holding page appeared after the page painted). The
+ * logo sibling of icons-render-ssr-inline. Size-capped: a pathological
+ * (>MAX_INLINE_LOGO_BYTES) logo falls back to null rather than bloating the
+ * HTML; the page renders logo-less, never broken.
+ */
+export declare function resolveErrorPageLogo(serviceSlug: string): Promise<string | null>;
+export declare class PrimaryResourceMissingError extends Error {
+    readonly resourceType: string;
+    readonly httpStatus: number;
+    readonly empty: boolean;
+    constructor(resourceType: string, httpStatus?: number, opts?: {
+        empty?: boolean;
+    });
+}
+export declare function buildResourceNotFoundResponse(resourceType: string, logoUrl?: string | null, status?: number, opts?: {
+    homeUrl?: string;
+    empty?: boolean;
+}): Response;

package/src/resource-not-found.ts

@@ -30,7 +30,6 @@
 
 import { getClient } from "@teamscala/object-storage/create/client/get-client";
 import { createCache } from "@teamscala/cache/create-cache";
-import { createNotifyListener, getDirectDatabaseUrl } from "@teamscala/db/notify-listener/index";
 import { getServerClient } from "@teamscala/orpc/server-client-registry";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import { toAssetPath } from "@teamscala/formatters/asset-url";
@@ -262,12 +261,3 @@ export function buildResourceNotFoundResponse(
 		},
 	});
 }
-
-{
-	const _url = getDirectDatabaseUrl();
-	if (_url) {
-		createNotifyListener(_url).listen("registry_config_changed", () => {
-		logoCache.clear();
-		}).catch((e: unknown) => console.error("[cache-invalidation] subscribe failed: " + e));
-	}
-}

package/src/run-boot-hook-list.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Runs the service's boot hooks. A server_package registers a hook via
+ * ctx.registerBootHook during the mount phase; a hook registered by an
+ * INSTALLED server_package is intended to run (the package is installed
+ * because the service wants it). This therefore invokes EVERY registered
+ * hook — those declared in `service_install.boot_hooks[]` first (preserving
+ * their declared order), then any registered-but-undeclared hooks. Requiring a
+ * hook to be BOTH registered by its package AND re-declared in boot_hooks is a
+ * double-declaration footgun — it left the realtime-utils pg-notify bridge
+ * registered-but-never-invoked (boot_hooks was null), so the live-refresh
+ * relay never started (2026-06-29).
+ */
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+import type { MountRegistry } from "@teamscala/os/runtime-contracts/mount-context";
+export declare function runBootHookList(config: ServiceInstallConfig, mountRegistry: MountRegistry, serviceSlug: string): Promise<void>;

package/src/run-boot-hooks.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Runs service_install.boot_hooks in declaration order. A boot hook is a
+ * registry-declared, one-shot startup function that needs to execute after
+ * prisma + registry are ready but before the HTTP server starts serving.
+ * Used for custom startup logic (stale-run reconciliation, cache hydration,
+ * ALS seeding, long-running watcher start) that doesn't fit the pg-boss
+ * recurring model and is too specific to be a generic installer step.
+ *
+ * Each hook is resolved by dynamic-importing its handler_slug (or slug when
+ * handler_slug is absent) and awaiting its default export. The export must
+ * be an async function accepting a BootHookContext. Hooks are invoked in
+ * ascending order of their `order` field (default 100).
+ *
+ * Failures are fatal. The installer has no partial-boot concept: if a
+ * declared hook cannot run, the service is broken, and booting anyway would
+ * mask the regression. BootFatalError is thrown to propagate to the
+ * top-level boot-error handler.
+ */
+import type { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
+export interface BootHookContext {
+    serviceSlug: string;
+    config: ServiceInstallConfig;
+}
+export type BootHookHandler = (ctx: BootHookContext) => Promise<void> | void;
+export declare function runBootHooks(serviceSlug: string, config: ServiceInstallConfig): Promise<{
+    ran: string[];
+}>;

package/src/scala-tools-currency-watchdog.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Polls the installed scala-tools package against GitHub Packages and repairs
+ * stale daemon tooling by reinstalling and letting PM2 restart the process.
+ */
+export declare function startScalaToolsCurrencyWatchdog(): void;
+export declare function stopScalaToolsCurrencyWatchdog(): void;

package/src/security-headers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Middleware that injects security headers into every response.
+ * Uses Hono's secureHeaders as the base for standard headers (X-Content-Type-Options,
+ * X-Frame-Options, Referrer-Policy, etc.), then layers registry-driven CSP with
+ * nonce injection on top.
+ */
+import type { Context, Next } from "hono";
+export declare function injectSecurityHeaders(c: Context, next: Next): Promise<void>;

package/src/serve/serve.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @system runtime-serve
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Listener primitives. Provides the Bun.serve production listener (serveStart)
+ * and the WebSocket upgrade helper (upgradeWebSocket) that work identically
+ * dev and prod.
+ */
+import type { Hono } from "hono";
+/**
+ * Hono `upgradeWebSocket` helper bound to the same `createBunWebSocket()`
+ * pair that drives Bun.serve.websocket. Use exclusively from this package so
+ * the upgrade path and the message dispatch share state.
+ */
+export declare const upgradeWebSocket: import("hono/ws").UpgradeWebSocket<unknown, any, import("hono/ws").WSEvents<unknown>>;
+export interface ServeOptions {
+    /** TCP port to bind. */
+    port: number;
+    /** For logging only. */
+    serviceSlug: string;
+    /**
+     * Optional logger; defaults to console.
+     */
+    logger?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+export interface ServeHandle {
+    server: ReturnType<typeof Bun.serve>;
+    stop(): void;
+}
+/**
+ * Start Bun.serve listening on the configured port. Used by:
+ *   - bootUiService when running the production bundle (`bun dist/server/index.js`)
+ *   - bootBackendService for non-UI services
+ *
+ * UI services in dev mode also call this — they run `bun src/index.ts`
+ * directly under PM2 with the same Bun.serve listener.
+ *
+ * Two-phase boot variant: when useMutableRef is true, `app` is used as the
+ * initial app for the mutable reference (minimal tool-only surface), and the
+ * caller can swap to the full app later via swapApp().
+ */
+export declare function serveStart(app: Hono, options: ServeOptions, useMutableRef?: boolean): ServeHandle;

package/src/serve/stamp-transport-identity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Stamp transport-derived identity onto a request — the single shared stamp
+ * point used by BOTH serve paths (direct `createFetchHandler` + mutable-ref
+ * `fetchWithMutableApp`), so every request on every UI service carries the
+ * same identity regardless of boot mode.
+ *
+ * Two identity layers, both transport-derived (no-client-controlled-trust-
+ * signals — never from a client-controllable header):
+ *   1. `x-caller-remote-address` / `-port` — the unforgeable socket peer, from
+ *      `Bun.serve.requestIP`. ALWAYS sanitised (any client-supplied spoof
+ *      deleted) then set to the verified peer. The /mcp + fleet loopback gates
+ *      read this.
+ *   2. `x-caller-local-comm` / `-cmd` — for a LOOPBACK peer with no forwarding
+ *      header (a local `fetch` carries no CF-Connecting-IP), the owning local
+ *      PROCESS resolved via /proc (@teamscala/proc-walker). Names the daemon
+ *      behind every local request on the access log — including an unidentified
+ *      sweeper. Attribution only (trust stays transport-derived).
+ *
+ * Best-effort + never throws: a resolution miss returns the original request
+ * unchanged (the request is always served; identity degrades to address-only).
+ * WebSocket upgrades are returned untouched (Bun tracks upgrades by Request
+ * identity — a clone can never upgrade).
+ */
+/**
+ * Return a Request with transport-identity headers stamped, or the original
+ * `req` when no stamping is needed/possible. Never throws.
+ */
+export declare function stampTransportIdentity(req: Request, server: ReturnType<typeof Bun.serve>): Request;

package/src/serve/stamp-transport-identity.ts

@@ -31,18 +31,6 @@ import { resolveSocketPeer } from "@teamscala/proc-walker/socket-peer";
 
 const LOOPBACK = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
 
-/**
- * Preserve useful process attribution without copying arbitrary argv into logs.
- * Arguments routinely contain bearer headers, inline scripts, URLs and secret
- * values. There is no complete flag-name redaction list, so the safe boundary
- * is structural: retain argv[0] and state that arguments were removed.
- */
-export function summariseLocalCommand(cmdline: readonly string[]): string | null {
-	const executable = cmdline[0]?.trim();
-	if (!executable) return null;
-	return cmdline.length > 1 ? `${executable} [arguments redacted]` : executable;
-}
-
 /**
  * Return a Request with transport-identity headers stamped, or the original
  * `req` when no stamping is needed/possible. Never throws.
@@ -89,8 +77,8 @@ export function stampTransportIdentity(
 			const owner = resolveSocketPeer(port);
 			if (owner) {
 				headers.set(CALLER_HEADERS.LOCAL_COMM, owner.comm);
-				const cmd = summariseLocalCommand(owner.cmdline);
-				if (cmd) headers.set(CALLER_HEADERS.LOCAL_CMD, cmd);
+				const cmd = owner.cmdline.join(" ").trim();
+				if (cmd) headers.set(CALLER_HEADERS.LOCAL_CMD, cmd.slice(0, 160));
 			}
 		}
 		return new Request(req.url, {