openmausbot 0.1.75 → 0.1.77

package/dist-server/server/team-setup-requests.js

@@ -0,0 +1,252 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { newId } from "./contracts.js";
+import { fitsOnOneLine, parseBotProfilePatch } from "./bot-profile.js";
+import { profileSnapshot } from "./profile-revision.js";
+import { redactSecretsInText } from "./redact.js";
+const section = (value) => value?.trim() || "";
+const teamName = z.string().trim().min(1).max(60).refine(fitsOnOneLine).refine((value) => redactSecretsInText(value) === value, "Team names cannot contain credentials");
+const fieldsSchema = z.object({
+    name: z.string().optional(), title: z.string().optional(), description: z.string().optional(), soul: z.string().optional(),
+    section: z.string().trim().max(60).refine(fitsOnOneLine).refine((value) => redactSecretsInText(value) === value, "Team names cannot contain credentials").optional(),
+    modelSelection: z.object({ instanceId: z.string().trim().min(1), model: z.string().trim().min(1), effort: z.string().optional() }).strict().optional(),
+}).strict();
+const planSchema = z.object({
+    reason: z.string().trim().min(1).max(500),
+    newTeams: z.array(teamName).max(8).default([]),
+    operations: z.array(z.discriminatedUnion("action", [
+        z.object({ action: z.literal("create"), key: z.string().trim().min(1).max(80), fields: fieldsSchema }).strict(),
+        z.object({ action: z.literal("update"), botId: z.string().min(1).max(128), fields: fieldsSchema }).strict(),
+    ])).min(1).max(24),
+}).strict();
+export class TeamSetupError extends Error {
+    status;
+    constructor(message, status = 400) { super(message); this.status = status; }
+}
+/** Settings relevant to approval, including the previous durable receipt. */
+export function teamSetupRevision(bot) {
+    return createHash("sha256").update(JSON.stringify({
+        ...profileSnapshot(bot), section: section(bot.section), modelSelection: bot.modelSelection,
+        hidden: Boolean(bot.hidden), chiefOfStaff: Boolean(bot.chiefOfStaff), peers: bot.peers,
+        managedSections: bot.managedSections,
+        approvalMode: bot.approvalMode, autoApprove: bot.autoApprove, approvalGrant: bot.approvalGrant,
+        receipt: bot.lastTeamSetupReceipt?.requestId,
+    })).digest("hex");
+}
+export class TeamSetupRequestService {
+    resolving = new Set();
+    options;
+    constructor(options) { this.options = options; }
+    chief(botId) {
+        const chief = this.options.store.bot(botId);
+        if (!chief || chief.hidden || !chief.chiefOfStaff)
+            throw new TeamSetupError("Only an active Chief of Staff can propose team setup", 403);
+        return chief;
+    }
+    fields(input, current) {
+        const { section: targetSection, modelSelection, ...profile } = input;
+        const safe = Object.fromEntries(Object.entries(profile).map(([key, value]) => [key, redactSecretsInText(value)]));
+        const parsed = parseBotProfilePatch(safe, true);
+        if (!parsed.ok)
+            throw new TeamSetupError(parsed.error);
+        const result = { ...parsed.patch };
+        if (targetSection !== undefined)
+            result.section = targetSection;
+        if (modelSelection) {
+            const selection = modelSelection;
+            const error = this.options.validateModel(selection, current);
+            if (error)
+                throw new TeamSetupError(error);
+            result.modelSelection = selection;
+        }
+        return result;
+    }
+    validate(request, confirming) {
+        const chief = this.chief(request.botId);
+        if (!this.options.ownsThread(request.botId, request.threadId))
+            throw new TeamSetupError("The requesting conversation no longer exists", 409);
+        if (confirming && !this.options.store.messagesFor(request.threadId).some((message) => message.card?.requestId === request.requestId && !message.card.answered && !message.card.dismissed))
+            throw new TeamSetupError("This setup card is no longer pending", 409);
+        if (confirming && teamSetupRevision(chief) !== request.requesterRevision)
+            throw new TeamSetupError("The Chief's settings changed. This setup was cancelled; review a new proposal.", 409);
+        const existingTeams = new Set(this.options.teams().map(section));
+        if (new Set([...(chief.managedSections ?? []), ...request.newTeams]).size > 100)
+            throw new TeamSetupError("A Chief may coordinate at most 100 additional teams", 409);
+        for (const name of request.newTeams)
+            if (existingTeams.has(name))
+                throw new TeamSetupError(`Team ${JSON.stringify(name)} now exists. Review a new proposal.`, 409);
+        const allowed = (name) => request.newTeams.includes(section(name)) || this.options.canAccessTeam(chief, name);
+        const targets = new Set();
+        const projected = this.options.store.bots.map((bot) => ({ id: bot.id, name: bot.name, section: section(bot.section), chiefOfStaff: bot.chiefOfStaff, hidden: bot.hidden }));
+        for (const operation of request.operations) {
+            if (targets.has(operation.botId))
+                throw new TeamSetupError("A bot appears twice in the prepared setup");
+            targets.add(operation.botId);
+            const target = this.options.store.bot(operation.botId);
+            if (operation.action === "create") {
+                if (target)
+                    throw new TeamSetupError("A proposed bot already exists. Review a new proposal.", 409);
+                if (!operation.fields.name?.trim() || !operation.fields.title?.trim() || !operation.fields.soul?.trim() || !operation.fields.modelSelection)
+                    throw new TeamSetupError("Each new bot needs a name, title, soul instructions, and exact model selection");
+            }
+            else {
+                if (!target || target.hidden || !this.options.canAccessTeam(chief, target.section) || (target.id !== chief.id && Array.isArray(chief.peers) && !chief.peers.includes(target.id)))
+                    throw new TeamSetupError("A target bot is outside this Chief's authorized team and peer scope", 403);
+                if (teamSetupRevision(target) !== operation.expectedRevision)
+                    throw new TeamSetupError(`@${target.name} changed. This setup was cancelled; review a new proposal.`, 409);
+                if (this.options.targetBusy(target.id) && (confirming || target.id !== chief.id))
+                    throw new TeamSetupError(`Stop @${target.name}'s work before changing its setup`, 409);
+            }
+            const fields = this.fields(operation.fields, target ?? undefined);
+            const destination = fields.section ?? target?.section ?? chief.section;
+            if (!allowed(destination))
+                throw new TeamSetupError("The destination team is outside this Chief's authorized scope", 403);
+            if (!request.newTeams.includes(section(destination)) && !existingTeams.has(section(destination)))
+                throw new TeamSetupError("The destination team no longer exists", 409);
+            const next = { id: operation.botId, name: fields.name ?? target.name, section: section(destination), chiefOfStaff: target?.chiefOfStaff, hidden: false };
+            const at = projected.findIndex((bot) => bot.id === operation.botId);
+            if (at < 0)
+                projected.push(next);
+            else
+                projected[at] = next;
+        }
+        if (this.options.store.bots.length + request.operations.filter((op) => op.action === "create").length > this.options.maxBots)
+            throw new TeamSetupError("This setup exceeds the workspace bot limit", 409);
+        for (const name of request.newTeams)
+            if (!request.operations.some((op) => section(op.fields.section) === name))
+                throw new TeamSetupError(`New team ${JSON.stringify(name)} needs a specialist in this setup`);
+        for (const operation of request.operations) {
+            const candidate = projected.find((bot) => bot.id === operation.botId);
+            if (projected.some((bot) => bot.id !== candidate.id && !bot.hidden && bot.section === candidate.section && bot.name.trim().toLowerCase() === candidate.name.trim().toLowerCase()))
+                throw new TeamSetupError(`@${candidate.name} already exists in that team`, 409);
+            if (candidate.chiefOfStaff && projected.some((bot) => bot.id !== candidate.id && bot.chiefOfStaff && bot.section === candidate.section))
+                throw new TeamSetupError("That move would put two Chiefs in one team", 409);
+        }
+        if (request.deletion) {
+            const target = this.options.store.bot(request.deletion.botId);
+            if (!target || target.hidden || target.id === chief.id || !this.options.canAccessTeam(chief, target.section) || (Array.isArray(chief.peers) && !chief.peers.includes(target.id)))
+                throw new TeamSetupError("This deletion target is no longer an authorized teammate", 403);
+            if (teamSetupRevision(target) !== request.deletion.expectedRevision || this.options.targetBusy(target.id))
+                throw new TeamSetupError("The deletion target changed or is working. Review a new deletion proposal.", 409);
+        }
+    }
+    propose(args) {
+        const parsed = planSchema.safeParse(args.plan);
+        if (!parsed.success)
+            throw new TeamSetupError(parsed.error.issues[0]?.message ?? "Invalid team setup");
+        const chief = this.chief(args.botId);
+        const combined = new Map();
+        for (const operation of parsed.data.operations) {
+            const key = operation.action === "create" ? `create:${operation.key}` : `update:${operation.botId}`;
+            const previous = combined.get(key);
+            combined.set(key, { ...operation, fields: { ...previous?.fields, ...operation.fields } });
+        }
+        if (combined.size > 8)
+            throw new TeamSetupError("Review at most eight bots in one setup");
+        const operations = [...combined.values()].map((operation) => {
+            const target = operation.action === "update" ? this.options.store.bot(operation.botId) : undefined;
+            return { action: operation.action, botId: operation.action === "create" ? newId() : operation.botId,
+                ...(operation.action === "create" ? { threadId: newId() } : {}),
+                fields: this.fields({ ...operation.fields, section: operation.fields.section ?? target?.section ?? chief.section ?? "" }, target ?? undefined),
+                ...(target ? { expectedRevision: teamSetupRevision(target) } : {}),
+            };
+        });
+        const request = { version: 1, requestId: newId(), botId: args.botId, threadId: args.threadId,
+            reason: redactSecretsInText(parsed.data.reason), createdAt: Date.now(), requesterRevision: teamSetupRevision(chief),
+            newTeams: [...new Set(parsed.data.newTeams)], operations };
+        this.validate(request, false);
+        return this.card(request, args.from);
+    }
+    proposeDeletion(args) {
+        const chief = this.chief(args.botId);
+        const target = this.options.store.bot(args.targetBotId);
+        if (!target)
+            throw new TeamSetupError("That bot no longer exists", 404);
+        if (!args.reason.trim() || args.reason.length > 500)
+            throw new TeamSetupError("A deletion reason of at most 500 characters is required");
+        const request = { version: 1, requestId: newId(), botId: args.botId, threadId: args.threadId,
+            reason: redactSecretsInText(args.reason), createdAt: Date.now(), requesterRevision: teamSetupRevision(chief), newTeams: [], operations: [],
+            deletion: { botId: target.id, name: target.name, expectedRevision: teamSetupRevision(target) } };
+        this.validate(request, false);
+        return this.card(request, args.from);
+    }
+    card(request, from) {
+        const permission = this.options.canPersist(request.botId, request.threadId);
+        if (!permission.ok)
+            throw new TeamSetupError(permission.error, permission.status);
+        const chief = this.chief(request.botId);
+        const lines = [`Why: ${request.reason}`];
+        if (request.deletion)
+            lines.push(`Delete @${request.deletion.name} (${request.deletion.botId}).`, "Permanently removes this bot, all its conversations, memory, instructions, and skills. Generated project files remain. Active work or owned computers can block deletion.");
+        if (request.newTeams.length)
+            lines.push(`Create teams: ${request.newTeams.map((name) => JSON.stringify(name)).join(", ")}.`, `Authorize @${chief.name} to coordinate and propose setup changes in these new teams.`);
+        for (const operation of request.operations) {
+            const current = this.options.store.bot(operation.botId);
+            lines.push(`\n${operation.action === "create" ? "Create" : "Update"} @${operation.fields.name ?? current?.name} (${operation.action === "create" ? "new bot" : operation.botId})`);
+            for (const [key, value] of Object.entries(operation.fields)) {
+                const before = current ? (key === "section" ? current.section || "General" : current[key]) : undefined;
+                lines.push(`${key === "modelSelection" ? "Default engine/model" : key}: ${current ? `${JSON.stringify(before ?? "")} → ` : ""}${key === "section" ? JSON.stringify(value || "General") : JSON.stringify(value)}`);
+            }
+        }
+        if (!request.deletion)
+            lines.push("\nDefault models apply to groups and new threads. Every existing thread keeps its current model and permissions.", "New bots start in Ask with connected apps disabled. Existing execution permissions are unchanged.");
+        lines.push("After this decision the Chief continues once with the result.");
+        const title = request.deletion ? `Delete @${request.deletion.name}?` : `Apply setup for ${request.operations.length} ${request.operations.length === 1 ? "bot" : "bots"}?`;
+        const detail = lines.join("\n");
+        const message = this.options.store.appendMessage(request.threadId, { role: "bot", kind: "options", ...(from ? { from } : {}), card: {
+                title, subtitle: detail, options: [request.deletion ? "Delete bot" : "Apply setup", "Cancel"], requestId: request.requestId,
+                tool: request.deletion ? "delete_bot" : "set_up_team", teamSetupRequest: request,
+            } });
+        return { requestId: request.requestId, messageId: message.id, title, summary: title, detail };
+    }
+    async resolve(args) {
+        const message = this.options.store.messagesFor(args.threadId).find((item) => item.card?.requestId === args.requestId && item.card.teamSetupRequest);
+        const card = message?.card, request = card?.teamSetupRequest;
+        if (!message || !card || !request)
+            return null;
+        if (request.botId !== args.botId || request.threadId !== args.threadId || request.requestId !== args.requestId)
+            throw new TeamSetupError("This setup belongs to another conversation", 403);
+        if (args.behavior !== "allow" && args.behavior !== "deny")
+            throw new TeamSetupError("Confirm or cancel this setup", 400);
+        // Stop/dismiss can close a card without a setup decision. It must never
+        // resurrect that review or wake the stopped conversation.
+        if (card.answered || card.dismissed) {
+            const result = request.result ?? { state: "cancelled", bots: [], newTeams: [], error: "This setup card was closed" };
+            return { result, request: { ...request, result }, messageId: message.id, duplicate: true };
+        }
+        if (this.resolving.has(request.requestId))
+            throw new TeamSetupError("This setup is already being applied", 409);
+        this.resolving.add(request.requestId);
+        try {
+            const receipt = this.options.store.bot(request.botId)?.lastTeamSetupReceipt;
+            let result;
+            if (receipt?.requestId === request.requestId)
+                result = receipt.result;
+            else if (args.behavior === "deny")
+                result = { state: "denied", bots: [], newTeams: [] };
+            else {
+                try {
+                    this.validate(request, true);
+                    if (request.deletion) {
+                        await this.options.deleteBot(request.deletion.botId, () => this.validate(request, true), request);
+                        result = { state: "applied", bots: [{ id: request.deletion.botId, name: request.deletion.name, action: "deleted" }], newTeams: [] };
+                    }
+                    else
+                        result = this.options.store.applyTeamSetup(request);
+                }
+                catch (error) {
+                    const saved = this.options.store.bot(request.botId)?.lastTeamSetupReceipt;
+                    const detail = redactSecretsInText(error instanceof Error ? error.message : String(error));
+                    result = saved?.requestId === request.requestId
+                        ? { ...saved.result, error: `The changes were saved, but cleanup needs attention: ${detail}` }
+                        : { state: error instanceof TeamSetupError ? "cancelled" : "failed", bots: [], newTeams: [], error: detail };
+                }
+            }
+            this.options.store.patchMessage(args.threadId, message.id, { card: { ...card, answered: result.state === "applied" ? "allow" : "deny", held: result.error, teamSetupRequest: { ...request, result } } });
+            return { result, request: { ...request, result }, messageId: message.id, duplicate: false };
+        }
+        finally {
+            this.resolving.delete(request.requestId);
+        }
+    }
+}

package/dist-server/server/tool-summary.js

@@ -1,7 +1,59 @@
 // What a tool call is about to do, in words a chip or a permission card can
 // show. Redacted before it is cut: a command line is where credentials get
 // pasted, and a key sliced in half would slip past the shapes redaction knows.
-import { redactSecretsInText } from "./redact.js";
+import { redactSecrets, redactSecretsInText } from "./redact.js";
+/** Display-only excerpt, never the raw protocol payload. Bound traversal and
+ * omit binary bodies before redacting; truncate only AFTER redaction so a
+ * credential cannot be cut in half and escape detection. */
+export function toolDetailPreview(value) {
+    if (value === undefined)
+        return undefined;
+    let budget = 200;
+    let textBudget = 256_000;
+    const bounded = (item, depth = 0) => {
+        if (--budget < 0 || depth > 6)
+            return "[additional data omitted]";
+        if (typeof item === "string") {
+            if (item.length > textBudget)
+                return "[large content omitted]";
+            if (/^data:[^,\s]+;base64,/i.test(item))
+                return "[binary content omitted]";
+            // MCP frequently puts JSON inside text content. Recover its field
+            // names so short credentials get the same masking as native objects.
+            if (/^\s*[[{]/.test(item)) {
+                try {
+                    return bounded(JSON.parse(item), depth + 1);
+                }
+                catch { /* ordinary text/code: use the content redactor below */ }
+            }
+            textBudget -= item.length;
+            return item;
+        }
+        if (typeof item === "bigint")
+            return String(item);
+        if (item === null || typeof item !== "object")
+            return item;
+        if (Array.isArray(item))
+            return item.slice(0, 40).map((child) => bounded(child, depth + 1)).concat(item.length > 40 ? ["[additional items omitted]"] : []);
+        const entries = Object.entries(item);
+        const result = Object.create(null);
+        for (const [key, child] of entries.slice(0, 40)) {
+            result[key] = /token|secret|password|passwd|cookie|authorization|api.?key|(^|[_.-])keys?$/i.test(key)
+                ? "[redacted]"
+                : /^(data|base64|blob)$/i.test(key) && typeof child === "string"
+                    ? "[binary content omitted]"
+                    : bounded(child, depth + 1);
+        }
+        if (entries.length > 40)
+            result["…"] = "[additional fields omitted]";
+        return result;
+    };
+    const safe = redactSecrets(bounded(value));
+    const text = typeof safe === "string" ? safe : JSON.stringify(safe, null, 2);
+    if (!text?.trim() || text === "{}" || text === "[]")
+        return undefined;
+    return text.length > 6_000 ? `${text.slice(0, 6_000)}\n[… preview shortened]` : text;
+}
 const QUESTION_LIMIT = 300;
 const LIMIT = 200;
 function fieldsOf(input) {

package/dist-server/server/turn-dispatch-guard.js

@@ -44,8 +44,11 @@ export class RetiredTurnRegistry {
 export class ProviderTurnGenerationRegistry {
     #owners = new Map();
     #completed;
+    #earlyCompletions = new Map();
+    #limit;
     constructor(limit = 4_096) {
         this.#completed = new RetiredTurnRegistry(limit);
+        this.#limit = limit;
     }
     bind(threadId, generation, turnId) {
         if (this.#completed.has(turnId))
@@ -53,23 +56,48 @@ export class ProviderTurnGenerationRegistry {
         this.#owners.set(turnId, { threadId, generation });
         return true;
     }
-    complete(threadId, turnId) {
-        this.#completed.retire(turnId);
+    complete(threadId, turnId, outcome) {
+        if (this.#completed.has(turnId))
+            return null;
         const owner = this.#owners.get(turnId);
-        if (!owner || owner.threadId !== threadId)
+        if (owner && owner.threadId !== threadId)
             return null;
+        this.#completed.retire(turnId);
+        if (!owner) {
+            // Only a later ACK for this exact provider id may consume the result.
+            // Never attribute an unbound event to the thread's current generation.
+            if (outcome !== undefined) {
+                this.#earlyCompletions.set(turnId, { threadId, outcome });
+                while (this.#earlyCompletions.size > this.#limit) {
+                    this.#earlyCompletions.delete(this.#earlyCompletions.keys().next().value);
+                }
+            }
+            return null;
+        }
         this.#owners.delete(turnId);
         return owner;
     }
+    takeEarlyCompletion(threadId, turnId) {
+        const receipt = this.#earlyCompletions.get(turnId);
+        if (receipt?.threadId !== threadId)
+            return undefined;
+        this.#earlyCompletions.delete(turnId);
+        return receipt.outcome;
+    }
     deleteGeneration(threadId, generation) {
+        const removed = [];
         for (const [turnId, owner] of this.#owners) {
             if (owner.threadId === threadId && owner.generation === generation) {
                 this.#owners.delete(turnId);
+                this.#completed.retire(turnId);
+                removed.push(turnId);
             }
         }
+        return removed;
     }
     clear() {
         this.#owners.clear();
+        this.#earlyCompletions.clear();
     }
 }
 /** Thread gate for the narrow interval after Stop wins but before an async

package/dist-server/server/workspace-backup.js

@@ -23,6 +23,7 @@ const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}
 const EXCLUDED = new Set([
     ".backups", "tools", "cache", ".cache", "tmp", ".tmp", "dist-native", "tunnel-runtime",
     ".openmausbot-server-child", "environment-id", "sessions.json", "tunnel-account.json",
+    "team-computers.json",
     "openmausbot-server.lease", "box-create-requests.lock", "messages.db-wal", "messages.db-shm",
 ]);
 const EXCLUSION_NOTES = [

package/dist-server/shared/approval-mode.js

@@ -16,6 +16,13 @@ export function supportsApprovalMode(driverKind, mode) {
         return true;
     return ["codex", "claudeAgent", "antigravityAgent", "cursorAgent", "grokAgent", "opencodeGo"].includes(driverKind ?? "");
 }
+/** A Full/Custom grant belongs to one provider's tool semantics. Other
+ * modes carry across only when the destination actually implements them.
+ * Adapted from tahodev's provider-switch guard in PR #1120. */
+export function modelSwitchNeedsAsk(mode, fromDriver, toDriver) {
+    return !supportsApprovalMode(toDriver, mode) ||
+        ((mode === "full" || mode === "custom") && fromDriver !== toDriver);
+}
 export function hasNativeAutoReview(driverKind) {
     return ["codex", "claudeAgent", "cursorAgent", "grokAgent"].includes(driverKind ?? "");
 }
@@ -27,7 +34,10 @@ export function isApprovalMode(value) {
  * behavior: autoApprove=true is safe Auto; everything else asks. Unknown
  * persisted values also fail closed to that legacy behavior. */
 export function approvalModeFor(bot) {
-    if (bot.approvalGrant)
+    const grant = bot.approvalGrant;
+    const otherThread = grant && typeof grant === "object" && "threadOnly" in grant && grant.threadOnly === true &&
+        "threadId" in grant && typeof grant.threadId === "string" && typeof bot.threadId === "string" && grant.threadId !== bot.threadId;
+    if (grant && !otherThread)
         return "ask";
     if (isApprovalMode(bot.approvalMode))
         return bot.approvalMode;

package/dist-server/shared/team-backup.js

@@ -21,6 +21,7 @@ const task = z.object({
     title: z.string().max(2_000),
     createdAt: timestamp,
     openedBy: z.object({ botId: key, name, at: timestamp }).optional(),
+    closedBy: z.object({ botId: key, name, at: timestamp }).optional(),
     activeLeafId: key.nullable(),
     messages: z.array(message).max(100_000),
 });

package/dist-server/shared/team-computer.js

@@ -0,0 +1 @@
+export {};

package/dist-server/shared/team-setup.js

@@ -0,0 +1 @@
+export {};

package/dist-server/vps-container-mcp.js

@@ -15112,7 +15112,11 @@ var featureConfigSchema = external_exports.object({
   showToolCalls: external_exports.boolean().optional(),
   /** Experimental built-in browser. Off until explicitly enabled; each bot
    * also has its own switch. */
-  browser: external_exports.boolean().optional()
+  browser: external_exports.boolean().optional(),
+  /** Opt-in computer sharing (a desktop lending folders, a terminal or
+   * computer control to a workspace). Off until explicitly enabled; there is
+   * no Settings toggle — see sharedComputersEnabled. */
+  sharedComputers: external_exports.boolean().optional()
 });
 var onboardingConfigSchema = external_exports.object({
   /** ISO timestamp of finishing (or skipping to the end of) the welcome flow. */

package/enterprise/README.md

@@ -23,8 +23,11 @@ customer, because the key decides the feature set rather than the code.
 { "edition": "oss", "features": [], "notice": "OMB_LICENSE_KEY expired on 2027-09-02; renew it to keep enterprise features" }
 ```
 
-A missing, altered, or expired key never stops the server: it runs the
-open-source edition and the notice says what to fix.
+A missing, altered, or expired key does not stop an ordinary standalone
+server: it runs the open-source edition and the notice says what to fix.
+A workspace explicitly configured for hosted sign-in fails closed for remote
+access when its `admin` entitlement or identity service is unavailable. It
+must not silently fall back to standalone email or pairing credentials.
 
 ## Entitlement ids
 
@@ -32,7 +35,7 @@ open-source edition and the notice says what to fix.
 |---|---|
 | `whitelabel` | product name, tagline, accent colour, logo, favicon and support link from `brand.json` (below) |
 | `sso` | identity-header trust behind an OIDC proxy |
-| `admin` | the admin panel routes |
+| `admin` | Settings → Workspaces and the optional hosted workspace sign-in adapter |
 | `budgets` | per-bot and per-section spend limits |
 
 Core gates a feature with `entitled("id")` from `server/enterprise.ts`.
@@ -59,6 +62,21 @@ working until they expire.
 - Customer-specific brand, skills, packages, connectors? The customer's own
   repo: data and config, never a fork.
 
+## Hosted workspace sign-in (`admin`)
+
+The workspace-side adapter in `server/workspace-access.ts` connects to an
+independently deployed identity service over HTTPS. The service's console,
+invitations, provider gateway and deployment automation are not shipped in
+this repository. The desktop and ordinary self-hosted server do not start
+or depend on a hosted console.
+
+Operators opt a workspace into this protocol using `OMB_ADMIN_URL`,
+`OMB_ADMIN_WORKSPACE` and `OMB_PUBLIC_URL`; a valid `admin` entitlement is
+required. The default keeps the local sign-in allow-list as an additional,
+narrowing check. Operators may explicitly delegate membership for verified
+portal sessions with `OMB_ADMIN_MEMBERSHIP=portal`; this never exempts ordinary
+email or pairing sessions. See the [protocol and isolated verification recipe](../docs/verification/hosted-workspaces.md).
+
 ## White-label (`whitelabel`)
 
 Put a `brand.json` in the server's data dir (`OMB_DATA_DIR`, the `/data`