pilotswarm 0.5.30 → 0.5.32

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pilotswarm",
-    "version": "0.5.30",
+    "version": "0.5.32",
     "description": "PilotSwarm application package: terminal UI, browser portal + Web API server, and MCP server — one install, three bins.",
     "type": "module",
     "license": "MIT",
@@ -81,7 +81,7 @@
         "ink": "^6.8.0",
         "jose": "^6.2.2",
         "mermaid": "^11.16.0",
-        "pilotswarm-sdk": "0.5.30",
+        "pilotswarm-sdk": "0.5.32",
         "react": "^19.2.4",
         "react-dom": "^19.2.4",
         "ws": "^8.18.2"

package/tui/src/node-sdk-transport.js

@@ -1172,6 +1172,10 @@ export class NodeSdkTransport {
         return this.mgmt.recordAuthzAudit(entry);
     }
 
+    async recordUserRole(principal, role) {
+        return this.mgmt.recordUserRole(principal, role);
+    }
+
     async listAuthzAudit(opts) {
         return this.mgmt.listAuthzAudit(opts);
     }

package/ui/core/src/controller.js

@@ -2814,6 +2814,29 @@ export class PilotSwarmUiController {
                     // the current package's workspace (stale-response race).
                     if (this.getState().admin?.packages?.selectedName !== name) return;
                     this.dispatch({ type: "admin/packages/tree/loaded", name, tree });
+                    // The package's own CHANGELOG, when it ships one. Loaded
+                    // alongside the tree rather than on demand because it is
+                    // the first thing a reviewer wants: what changed, why, and
+                    // whether an agent or a human authored it.
+                    const hasChangelog = tree?.files?.some((f) => f.path === "CHANGELOG.md");
+                    if (hasChangelog && typeof this.transport.getAgentPackageFile === "function") {
+                        void (async () => {
+                            try {
+                                const file = await this.transport.getAgentPackageFile(name, null, "CHANGELOG.md");
+                                if (this.getState().admin?.packages?.selectedName !== name) return;
+                                this.dispatch({
+                                    type: "admin/packages/changelog/loaded",
+                                    name,
+                                    content: typeof file === "string" ? file : (file?.content ?? file?.text ?? ""),
+                                });
+                            } catch {
+                                // A missing/unreadable changelog is not an error
+                                // worth interrupting package browsing for.
+                            }
+                        })();
+                    } else {
+                        this.dispatch({ type: "admin/packages/changelog/loaded", name, content: null });
+                    }
                     // Default preview: plugin.json (always present in a valid package).
                     const first = tree?.files?.find((f) => f.path === "plugin.json") ?? tree?.files?.[0];
                     if (first) void this.selectAdminPackageFile(first.path);
@@ -4422,16 +4445,53 @@ export class PilotSwarmUiController {
         this.dispatch({ type: "ui/chatViewMode", mode });
     }
 
-    async openSessionAgentPicker(options = {}) {
-        const agents = typeof this.transport.listCreatableAgents === "function"
-            ? await this.transport.listCreatableAgents()
-            : [];
+    /**
+     * Opens the agent step of the new-session flow.
+     *
+     * This step needs a network round trip (listCreatableAgents) before it can
+     * render, and it is reached from the middle of a modal chain. Callers used
+     * to close the current step BEFORE awaiting it, which left the overlay
+     * unmounted for the length of that fetch — the dialog visibly blinked out
+     * and back on the way to the agent list.
+     *
+     * So nothing is dismissed until we know what replaces it: on success the
+     * new modal REPLACES the open one in a single dispatch and the overlay
+     * never leaves the screen; only the paths that open no modal at all close
+     * it. `previousFocus` is threaded from the previous step because that step
+     * is deliberately still up, so it cannot be recovered from focus state.
+     */
+    async openSessionAgentPicker(options = {}, previousFocusOverride = null) {
+        const previousFocus = previousFocusOverride ?? this.getState().ui.focusRegion;
+        const dismiss = () => {
+            this.dispatch({ type: "ui/modal", modal: null });
+            if (previousFocus) {
+                this.setFocus(previousFocus);
+            }
+        };
+
+        let agents = [];
+        try {
+            agents = typeof this.transport.listCreatableAgents === "function"
+                ? await this.transport.listCreatableAgents()
+                : [];
+        } catch (error) {
+            // The previous step is deliberately still on screen. If the fetch
+            // fails we own dismissing it — otherwise the flow strands on a step
+            // whose Enter key has already been consumed.
+            dismiss();
+            this.dispatch({
+                type: "ui/status",
+                text: `Could not load agents: ${error?.message || error}`,
+            });
+            return;
+        }
         const sessionPolicy = typeof this.transport.getSessionCreationPolicy === "function"
             ? this.transport.getSessionCreationPolicy()
             : null;
         const allowGeneric = sessionPolicy?.creation?.allowGeneric ?? true;
 
         if (!Array.isArray(agents) || agents.length === 0) {
+            dismiss();
             if (!allowGeneric) {
                 this.dispatch({
                     type: "ui/status",
@@ -4503,7 +4563,7 @@ export class PilotSwarmUiController {
                 title: "Select agent for new session",
                 items,
                 selectedIndex: 0,
-                previousFocus: this.getState().ui.focusRegion,
+                previousFocus,
                 sessionOptions: options,
             },
         });
@@ -4526,13 +4586,17 @@ export class PilotSwarmUiController {
         await this.openSessionAgentPicker(options);
     }
 
-    async openReasoningEffortPicker(modelItem, sessionOptions = {}) {
+    // previousFocus rides along the whole chain: each step is left on screen
+    // until its successor is ready (see openSessionAgentPicker), so a later
+    // step cannot read the pre-modal focus back off the state.
+    async openReasoningEffortPicker(modelItem, sessionOptions = {}, previousFocusOverride = null) {
+        const previousFocus = previousFocusOverride ?? this.getState().ui.focusRegion;
         const supported = normalizeReasoningEfforts(modelItem?.supportedReasoningEfforts);
         const selectedEffort = sessionOptions?.reasoningEffort || resolveDefaultReasoningEffort(modelItem);
         if (!supported.length || !selectedEffort) {
             // No effort step for this model — fall through to the context-tier
             // step, which handles both the new-session and switch-model flows.
-            await this.openContextTierPicker(modelItem, sessionOptions);
+            await this.openContextTierPicker(modelItem, sessionOptions, previousFocus);
             return;
         }
 
@@ -4552,7 +4616,7 @@ export class PilotSwarmUiController {
                     : `Reasoning effort for ${modelItem?.modelName || modelItem?.qualifiedName || "model"}`,
                 items,
                 selectedIndex,
-                previousFocus: this.getState().ui.focusRegion,
+                previousFocus,
                 modelItem,
                 sessionOptions,
             },
@@ -4560,21 +4624,26 @@ export class PilotSwarmUiController {
         this.dispatch({ type: "ui/status", text: "Select a reasoning effort and press Enter" });
     }
 
-    async openContextTierPicker(modelItem, sessionOptions = {}) {
+    async openContextTierPicker(modelItem, sessionOptions = {}, previousFocusOverride = null) {
         // Context-window tier step of the new-session flow. Only models whose
         // catalog entry declares supportedContextTiers get this picker; all
         // others skip straight to the agent picker. The preselected tier is
         // the catalog default ("default", the smaller window).
+        const previousFocus = previousFocusOverride ?? this.getState().ui.focusRegion;
         const supported = normalizeContextTiers(modelItem?.supportedContextTiers);
         const selectedTier = sessionOptions?.contextTier || resolveDefaultContextTier(modelItem);
         if (!supported.length || !selectedTier) {
             // Model declares no context-window tiers — skip straight to applying
             // the switch (switch flow) or to the agent picker (new-session flow).
             if (sessionOptions?.mode === "switchModel") {
+                this.dispatch({ type: "ui/modal", modal: null });
+                if (previousFocus) {
+                    this.setFocus(previousFocus);
+                }
                 await this.switchSessionModel({ ...sessionOptions, model: modelItem?.id });
                 return;
             }
-            await this.openSessionAgentPicker(sessionOptions);
+            await this.openSessionAgentPicker(sessionOptions, previousFocus);
             return;
         }
 
@@ -4593,7 +4662,7 @@ export class PilotSwarmUiController {
                 title: `Context window for ${modelItem?.modelName || modelItem?.qualifiedName || "model"}`,
                 items,
                 selectedIndex,
-                previousFocus: this.getState().ui.focusRegion,
+                previousFocus,
                 modelItem,
                 sessionOptions,
             },
@@ -5914,17 +5983,20 @@ export class PilotSwarmUiController {
                 });
                 return;
             }
+            // Each successor opener replaces this modal itself, so the overlay
+            // is NOT dismissed here: doing that before an awaited step blinked
+            // the dialog off screen for the length of the step's fetch.
             const previousFocus = modal.previousFocus;
-            this.dispatch({ type: "ui/modal", modal: null });
-            if (previousFocus) {
-                this.setFocus(previousFocus);
-            }
             if (!item) {
                 if (modal.sessionOptions?.mode === "switchModel") {
+                    this.dispatch({ type: "ui/modal", modal: null });
+                    if (previousFocus) {
+                        this.setFocus(previousFocus);
+                    }
                     this.dispatch({ type: "ui/status", text: "No model selected" });
                     return;
                 }
-                await this.openSessionAgentPicker({});
+                await this.openSessionAgentPicker({}, previousFocus);
                 return;
             }
             const defaultReasoning = resolveDefaultReasoningEffort(item);
@@ -5933,49 +6005,49 @@ export class PilotSwarmUiController {
                     ...(modal.sessionOptions || {}),
                     model: item.id,
                     reasoningEffort: defaultReasoning ?? null,
-                });
+                }, previousFocus);
                 return;
             }
             await this.openReasoningEffortPicker(item, {
                 ...(modal.sessionOptions || {}),
                 model: item.id,
                 ...(defaultReasoning ? { reasoningEffort: defaultReasoning } : {}),
-            });
+            }, previousFocus);
             return;
         }
         if (modal.type === "reasoningEffortPicker") {
             const item = modal.items?.[modal.selectedIndex || 0];
             const previousFocus = modal.previousFocus;
             const sessionOptions = modal.sessionOptions || {};
-            this.dispatch({ type: "ui/modal", modal: null });
-            if (previousFocus) {
-                this.setFocus(previousFocus);
-            }
+            // Not dismissed here — the tier step (or the agent step it falls
+            // through to) replaces this modal in one dispatch.
             await this.openContextTierPicker(modal.modelItem, {
                 ...sessionOptions,
                 ...(item?.id ? { reasoningEffort: item.id } : {}),
-            });
+            }, previousFocus);
             return;
         }
         if (modal.type === "contextTierPicker") {
             const item = modal.items?.[modal.selectedIndex || 0];
             const previousFocus = modal.previousFocus;
             const sessionOptions = modal.sessionOptions || {};
-            this.dispatch({ type: "ui/modal", modal: null });
-            if (previousFocus) {
-                this.setFocus(previousFocus);
-            }
             const nextOptions = {
                 ...sessionOptions,
                 ...(item?.id ? { contextTier: item.id } : {}),
             };
-            // Switch-model flow ends here — apply the model/effort/tier switch.
-            // New-session flow continues to the agent picker.
+            // Switch-model flow ends here — apply the model/effort/tier switch,
+            // so this one DOES close the overlay. The new-session flow continues
+            // to the agent picker, which replaces the modal itself once its
+            // agent list has loaded.
             if (sessionOptions?.mode === "switchModel") {
+                this.dispatch({ type: "ui/modal", modal: null });
+                if (previousFocus) {
+                    this.setFocus(previousFocus);
+                }
                 await this.switchSessionModel({ ...nextOptions, model: modal.modelItem?.id || sessionOptions.model });
                 return;
             }
-            await this.openSessionAgentPicker(nextOptions);
+            await this.openSessionAgentPicker(nextOptions, previousFocus);
             return;
         }
         if (modal.type === "sessionAgentPicker") {

package/ui/core/src/reducer.js

@@ -53,8 +53,38 @@ function isPinnableSession(session) {
     );
 }
 
+/**
+ * Keep a pin unless the row is loaded AND demonstrably no longer pinnable.
+ *
+ * Same rule, and the same reasoning, as pruneCollapsedIds below: a row missing
+ * from the current listing has NOT been unpinned. Not-loaded, filtered out,
+ * on another page, or simply slower to arrive are indistinguishable from here,
+ * and none of them is the user changing their mind.
+ *
+ * This ran unguarded on every `sessions/loaded`, so any listing that did not
+ * happen to contain the pinned row dropped the pin — and because pinnedIds is
+ * a dependency of the profile-save effect, the emptied list was then written
+ * back to the server as the user's preference. That is a one-way ratchet: the
+ * pin did not survive a restart, and the destroyed preference propagated to
+ * every other device, which is why a pin set on the desktop never reached the
+ * phone.
+ *
+ * A session that is genuinely present and NOT pinnable (moved into a group or
+ * under a parent, or a system row) is a real signal, so that still drops.
+ */
 function prunePinnedIds(ids, byId) {
-    return pruneIdList(ids, byId).filter((sessionId) => isPinnableSession(byId[sessionId]));
+    const out = [];
+    const seen = new Set();
+    for (const id of ids || []) {
+        if (!id || seen.has(id)) continue;
+        seen.add(id);
+        const session = byId?.[id];
+        // Absent from this listing tells us nothing — keep it. A stale id
+        // matches no row and hoists nothing; a wrongly dropped one costs the
+        // user their pin permanently.
+        if (!session || isPinnableSession(session)) out.push(id);
+    }
+    return out;
 }
 
 
@@ -2128,6 +2158,10 @@ export function appReducer(state, action) {
                         detail: null,
                         detailLoading: Boolean(action.name),
                         detailError: null,
+                        // Cleared on every selection: showing the previous
+                        // package's history under a new package is worse than
+                        // showing none.
+                        changelog: null,
                         action: { pending: null, error: null },
                         workspace: {
                             tree: null, treeLoading: Boolean(action.name), treeError: null,
@@ -2146,6 +2180,21 @@ export function appReducer(state, action) {
             if (state.admin.packages.selectedName !== action.name) return state;
             return { ...state, admin: { ...state.admin, packages: { ...state.admin.packages, detail: null, detailLoading: false, detailError: action.error || "Failed to load package" } } };
         }
+        case "admin/packages/changelog/loaded": {
+            // Stale-response guard, same as the tree: a slow changelog for a
+            // previously-selected package must not surface under the current one.
+            if (state.admin.packages.selectedName !== action.name) return state;
+            return {
+                ...state,
+                admin: {
+                    ...state.admin,
+                    packages: {
+                        ...state.admin.packages,
+                        changelog: action.content || null,
+                    },
+                },
+            };
+        }
         case "admin/packages/tree/loaded": {
             if (state.admin.packages.selectedName !== action.name) return state;
             const topDirs = Array.isArray(action.tree?.dirs)

package/ui/core/src/selectors.js

@@ -256,7 +256,7 @@ export function manualOrderContainerKey(session, pinned = false) {
  * plus a createdBy email. Resolving the package's principal against this
  * directory recovers the real name, which is what makes initials come out as
  * a person's initials ("Affan Dar" → AD) rather than the first two letters of
- * an alias ("daraffan@…" → DA). No fetch: the data is already loaded.
+ * an alias ("ada@…" → AD). No fetch: the data is already loaded.
  */
 /**
  * The one owner-badge descriptor both lists render from. Same person ⇒ same
@@ -290,7 +290,7 @@ function ownerDirectoryFromSessions(byId) {
  *
  * A DISPLAY NAME beats an email, because initials should be the person's
  * ("Affan Dar" → AD), not the first two letters of their alias
- * ("daraffan@…" → DA) — which is exactly the mismatch that made the same
+ * ("ada@…" → AD) — which is exactly the mismatch that made the same
  * person read differently in the session list and the package list.
  */
 function resolvePackageOwner(pkg, directory) {
@@ -342,29 +342,50 @@ export function ownerBadgeKey(owner, createdBy) {
     ).trim().toLowerCase();
 }
 
-function shouldDecorateSessionOwners(state) {
-    // Decorate owners only when the list actually surfaces more than one
-    // distinct human owner — otherwise the owner chip is pure noise on every
-    // row (you are always "you"). A narrowed owner filter is an explicit
-    // multi-user context, so honor that too.
-    // A narrowed filter counts as an explicit multi-user context ONLY when it
-    // names specific owners. The DEFAULT signed-in filter already sets
-    // `all: false` AND `includeShared: true` (see
-    // defaultOwnerFilterForPrincipal), so testing either of those tagged every
-    // row in a single-user deployment with a pointless "you are you" chip.
-    // Everything else falls through to counting DISTINCT owners below, which
-    // is what the chip actually communicates.
-    const ownerFilter = state.sessions?.ownerFilter;
-    if (Array.isArray(ownerFilter?.ownerKeys) && ownerFilter.ownerKeys.length > 0) return true;
+/**
+ * Distinct HUMAN owners **in the list** — where "the list" means the rows the
+ * owner filter admits, whether or not they happen to be on screen.
+ *
+ * That distinction is the whole rule, and the two halves pull in opposite
+ * directions on purpose:
+ *   - **Collapsing** a folder hides rows that are still in the list, so they
+ *     still count. A chip that appeared on expand and vanished on collapse
+ *     would be worse than no chip.
+ *   - **Filtering** takes rows out of the list entirely, so they stop counting.
+ *     Narrowing to "me + System" leaves one human, and one human needs no chip.
+ *
+ * "Human" excludes:
+ *   - `isSystem` rows (the permanent system agents);
+ *   - rows owned by the first-class System principal. Sessions a system agent
+ *     spawns on a user's behalf are NOT flagged isSystem — deliberately, so
+ *     they stay deletable (see SYSTEM_OWNER_KEY) — so gating on the flag alone
+ *     let "System" through as a second "person";
+ *   - unowned rows, whose owner key is null.
+ */
+function distinctHumanOwnerCount(state, stopAt = Infinity) {
+    const byId = state?.sessions?.byId;
+    const ownerFilter = state?.sessions?.ownerFilter || { all: true };
+    const auth = state?.auth || {};
     const owners = new Set();
-    for (const session of Object.values(state.sessions?.byId || {})) {
+    for (const session of Object.values(byId || {})) {
         if (!session || session.isSystem || session.isGroup) continue;
         const key = ownerKeyForOwner(session.owner);
-        if (!key) continue;
+        if (!key || key === SYSTEM_OWNER_KEY) continue;
+        // Only rows the filter admits. Uses the same predicate the rows
+        // themselves are filtered with, so the tally can never disagree with
+        // what is actually listed.
+        if (!matchesOwnerFilterDirect(session, ownerFilter, auth)) continue;
         owners.add(key);
-        if (owners.size > 1) return true;
+        if (owners.size >= stopAt) break;
     }
-    return false;
+    return owners.size;
+}
+
+function shouldDecorateSessionOwners(state) {
+    // One rule: the chip earns its place when the list holds more than one
+    // distinct human owner. Otherwise it is noise on every row — you are
+    // always "you".
+    return distinctHumanOwnerCount(state, 2) > 1;
 }
 
 function groupMemberSessions(group, byId = {}) {
@@ -3802,6 +3823,18 @@ export function selectAdminConsole(state) {
     );
     // Built once per render, not per row.
     const ownerDirectory = ownerDirectoryFromSessions(state?.sessions?.byId);
+    // Same rule as the session list: the owner chip only earns its place when
+    // this list actually holds more than one owner. Shared packages belong to
+    // the deployment, not a person, so they neither carry a chip nor count
+    // toward the tally.
+    const distinctPackageOwners = new Set();
+    for (const pkg of pkgList) {
+        if (pkg?.scope === "shared") continue;
+        const key = ownerKeyForOwner(pkg?.owner) || String(pkg?.createdBy || "").trim().toLowerCase();
+        if (!key || key === SYSTEM_OWNER_KEY) continue;
+        distinctPackageOwners.add(key);
+    }
+    const decoratePackageOwners = distinctPackageOwners.size > 1;
     const packageRow = (pkg) => ({
         name: pkg.name,
         scope: pkg.scope === "shared" ? "shared" : "user",
@@ -3815,7 +3848,9 @@ export function selectAdminConsole(state) {
         // the deployment and keep the scope badge instead.
         // Resolved against the session-owner directory so the initials are the
         // PERSON's, matching the session list exactly.
-        ownerBadge: pkg.scope === "shared" ? null : ownerBadgeFor(resolvePackageOwner(pkg, ownerDirectory)),
+        ownerBadge: (pkg.scope === "shared" || !decoratePackageOwners)
+            ? null
+            : ownerBadgeFor(resolvePackageOwner(pkg, ownerDirectory)),
         // Highlight only while the Agents section is active — otherwise the
         // GitHub Keys screen shows a double selection.
         selected: admin.section === "packages" && pkgState.selectedName === pkg.name,
@@ -4074,6 +4109,14 @@ export function selectAdminConsole(state) {
         selectedName: pkgState.selectedName || null,
         detail: packageDetail,
         workspace,
+        /**
+         * The package's own CHANGELOG.md, when it ships one.
+         *
+         * Passed through verbatim rather than parsed: it is authored markdown,
+         * and the renderer only needs to pick out headings and the signature
+         * line. Null when the package carries no changelog.
+         */
+        changelog: pkgState.changelog || null,
         addDialog: {
             open: Boolean(pkgState.addDialog?.open),
             kind: pkgState.addDialog?.kind || "repo",
@@ -7255,7 +7298,10 @@ export function selectInspector(state, options = {}) {
                 ]
                 : activeTab === "history"
                     ? [
-                        ...buildPaneTitleRuns(compactSecondaryMeta ? "History" : `History: ${shortId}`, "magenta"),
+                        // Named for what it actually shows: the durable Duroxide
+                        // event log. The compact branch abbreviates rather than
+                        // truncates — the full name overruns a narrow inspector.
+                        ...buildPaneTitleRuns(compactSecondaryMeta ? "Duroxide Events" : `Duroxide Event History: ${shortId}`, "magenta"),
                     ]
                     : activeTab === "stats"
                         ? [

package/ui/core/src/state.js

@@ -343,6 +343,8 @@ export function createInitialState({ mode = "local", branding = null, docs = nul
                 detail: null,
                 detailLoading: false,
                 detailError: null,
+                /** Raw CHANGELOG.md of the selected package, or null when it has none. */
+                changelog: null,
                 workspace: {
                     tree: null,
                     treeLoading: false,

package/ui/core/src/themes/doom.js

@@ -0,0 +1,106 @@
+import { createTheme } from "./helpers.js";
+
+// DOOM (id Software, 1993) — the status bar, not the shooter.
+//
+// The recognizable thing about DOOM's UI is STBAR: a band of hammered brown
+// metal carrying big red numerals and the marine's face. That maps onto a
+// portal header almost directly, so this theme is warm brown chrome around a
+// near-black ground, with bone-coloured type.
+//
+// The semantic palette is the THREE KEYCARDS — blue, yellow, red. Every player
+// already reads that triad as progress / caution / stop without being taught,
+// and it happens to be exactly the distinction a session list needs. Armor
+// green is held back for "completed".
+//
+// The ground is a red-biased near-black rather than pure #000: DOOM's letterbox
+// was black but everything in frame was warm, and a neutral black underneath
+// warm chrome reads as two unrelated themes stacked.
+const doomTheme = createTheme({
+    id: "doom",
+    label: "DOOM",
+    description: "STBAR brown metal, bone type, and the three keycards as the status palette.",
+    // The face, drawn as data rather than markup so ui/core stays free of any
+    // framework and nothing has to inject raw HTML. The portal renders it in
+    // place of the deployment's logo; the TUI ignores it.
+    //
+    // In DOOM the face was never decoration — it reported your state. Keeping
+    // it as the mark leaves that door open.
+    icon: {
+        viewBox: "0 0 32 32",
+        paths: [
+            { d: "M0 0h32v32H0z", fill: "#2a1d14" },              // recessed frame
+            { d: "M6 7h20v20H6z", fill: "#c89a6a" },              // face
+            { d: "M5 6h22v6H5z", fill: "#4a2f1a" },               // hair
+            { d: "M9 15h5v3.4H9z", fill: "#1a1008" },             // left eye
+            { d: "M18 15h5v3.4h-5z", fill: "#1a1008" },           // right eye
+            { d: "M8.6 13.6l6 1 -.3 1.7-6-1z", fill: "#3a2412" }, // brows, angled in
+            { d: "M23.4 13.6l-6 1 .3 1.7 6-1z", fill: "#3a2412" },
+            { d: "M14.5 18.5h3v2.4h-3z", fill: "#a8734a" },       // nose
+            { d: "M11 22h10v1.8H11z", fill: "#7a3a2a" },          // mouth
+        ],
+    },
+    page: {
+        background: "#100b09",
+        foreground: "#d9cba8",
+        overlayBackground: "#1c1310",
+        overlayForeground: "#d9cba8",
+        // 6.2:1 on the ground. Authentic DOOM shadow browns sit nearer 3:1 and
+        // would fail the muted-contrast bar the theme suite enforces, so this
+        // is lifted — the same deliberate deviation ms-dos.js documents for CGA
+        // dark grey.
+        hintColor: "#a08d68",
+        modalBackdrop: "rgba(16, 11, 9, 0.82)",
+        modalBackground: "#1c1310",
+        modalBorder: "#6f5432",
+        modalForeground: "#d9cba8",
+        modalMuted: "#a08d68",
+        // Selection is the STBAR band itself, not a tint.
+        modalSelectedBackground: "#6f5432",
+        modalSelectedBorder: "#a4885c",
+        modalSelectedForeground: "#fff4d6",
+    },
+    terminal: {
+        background: "#100b09",
+        foreground: "#d9cba8",
+        cursor: "#b81c1c",
+        cursorAccent: "#100b09",
+        selectionBackground: "#6f5432",
+        black: "#100b09",
+        // Health red, lifted a shade: the sprite value lands at 2.9994:1 on
+        // this ground — close enough to look fine and just under the 3:1 a
+        // status mark needs.
+        red: "#c42222",
+        green: "#3f9e3f",        // armor bonus
+        yellow: "#e8c020",       // yellow keycard
+        // Lifted from the sprite's #3050d0, which measures 2.97:1 on this
+        // ground — under the 3:1 a status dot needs. Still unmistakably the
+        // blue keycard, now legible.
+        blue: "#3a5ce0",
+        magenta: "#a0446a",
+        cyan: "#4a8f8f",
+        white: "#d9cba8",        // bone
+        brightBlack: "#a08d68",
+        brightRed: "#ff3a1e",
+        brightGreen: "#5fc45f",
+        brightYellow: "#ffd84a",
+        brightBlue: "#5a7ae8",
+        brightMagenta: "#c46a94",
+        brightCyan: "#6fb5b5",
+        brightWhite: "#fff4d6",
+    },
+    tui: {
+        border: "#6f5432",
+        // The transcript is prose, so speakers keep the keycard colours rather
+        // than everything collapsing into bone-on-brown.
+        userChat: "#e8c020",
+        userChatLabel: "#ffd84a",
+        selectionBackground: "#6f5432",
+        selectionForeground: "#fff4d6",
+        activeHighlightBackground: "#6f5432",
+        activeHighlightForeground: "#fff4d6",
+        promptCursorBackground: "#b81c1c",
+        promptCursorForeground: "#fff4d6",
+    },
+});
+
+export default doomTheme;

package/ui/core/src/themes/helpers.js

@@ -41,7 +41,7 @@ export function isThemeLight(theme) {
     return getRelativeLuminance(background) >= 0.5;
 }
 
-export function createTheme({ id, label, description, page, terminal, tui = {}, richChat = false }) {
+export function createTheme({ id, label, description, page, terminal, tui = {}, richChat = false, icon = null }) {
     const baseTui = {
         background: page?.background || terminal?.background || "#000000",
         surface: terminal?.background || page?.background || "#000000",
@@ -76,6 +76,12 @@ export function createTheme({ id, label, description, page, terminal, tui = {},
         // Portal-only: this theme renders the chat transcript in the rich
         // (desktop-style) view. The TUI ignores it.
         richChat: Boolean(richChat),
+        // Portal-only: an optional brand mark carried BY the theme. When set it
+        // outranks the deployment's own logo, because a theme that restyles the
+        // whole shell and then leaves a foreign logo in the corner reads as
+        // broken. Data, not markup — ui/core has no framework and must not
+        // inject HTML. Shape: { viewBox, paths: [{ d, fill }] }.
+        icon: icon || null,
         page,
         terminal,
         tui: {

package/ui/core/src/themes/index.js

@@ -15,6 +15,8 @@ import terminalGreenTheme from "./terminal-green.js";
 import highContrastMonoTheme from "./high-contrast-mono.js";
 import win95Theme from "./win95.js";
 import msDosTheme from "./ms-dos.js";
+import doomTheme from "./doom.js";
+import winampTheme from "./winamp.js";
 
 const THEMES = Object.freeze([
     workspaceDarkTheme,
@@ -34,6 +36,8 @@ const THEMES = Object.freeze([
     highContrastMonoTheme,
     win95Theme,
     msDosTheme,
+    doomTheme,
+    winampTheme,
 ].sort((left, right) => left.label.localeCompare(right.label, undefined, { sensitivity: "base" })));
 
 const THEME_MAP = new Map(THEMES.map((theme) => [theme.id, theme]));