@monster-orange/den 0.2.8 → 0.4.0

package/src/ui/mcp/scope.ts

@@ -4,11 +4,18 @@
  * filters lists to it, and stamps the actor on every web API call (the
  * x-den-mcp-agent / x-den-mcp-workspace headers, see shared/agent-actor.ts).
  *
+ * `--grant <ws>` (AG-2a, AG spec §5b; repeatable) widens the scope to another
+ * workspace, and only as far as the org config's `agents.<id>.grants` says
+ * (checkGrants): an agent never grants itself one. A call that names a
+ * granted workspace is served, and reported to the audit trail with both
+ * workspaces named. Lists show the scoped workspace and its grants.
+ *
  * It binds cooperating agents only: the scope lives in this process, and the
  * web server's HTTP API does not check it yet (WS-3a).
  */
 import * as path from "path";
 import { AGENT_ACTOR_RE, WORKSPACE_NAME_RE } from "../../shared/agent-actor.js";
+import type { ResolvedAgentsConfig } from "../../shared/den-config.js";
 import type { DenApi } from "./api.js";
 import { Refusal } from "./guards.js";
 
@@ -17,6 +24,16 @@ export interface McpScope {
   workspace: string;
   /** Who acts: `agent:<id>`. */
   actor: string;
+  /**
+   * Other workspaces it may name (`--grant`, from agents.<id>.grants);
+   * absent when there are none.
+   */
+  grants?: string[];
+}
+
+/** The workspaces a scope serves: its own first, then its grants. */
+export function scopeWorkspaces(scope: McpScope): string[] {
+  return [scope.workspace, ...(scope.grants ?? [])];
 }
 
 /** A call reached outside the scoped workspace. Always reported (F2). */
@@ -35,10 +52,11 @@ export class ScopeUsageError extends Error {
   }
 }
 
-const FLAGS: Record<string, "workspace" | "actor"> = {
+const FLAGS: Record<string, "workspace" | "actor" | "grant"> = {
   "--workspace": "workspace",
   "-w": "workspace",
   "--actor": "actor",
+  "--grant": "grant",
 };
 
 /**
@@ -53,6 +71,7 @@ export function parseScopeFlags(argv: readonly string[]): {
   rest: string[];
 } {
   const got: Partial<Record<"workspace" | "actor", string>> = {};
+  const grants: string[] = [];
   const rest: string[] = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -71,12 +90,25 @@ export function parseScopeFlags(argv: readonly string[]): {
         throw new ScopeUsageError(`${name} needs a value`);
       i++;
     }
+    if (key === "grant") {
+      if (!WORKSPACE_NAME_RE.test(value))
+        throw new ScopeUsageError(
+          `--grant "${printable(value)}" is not a workspace name`,
+        );
+      if (!grants.includes(value)) grants.push(value);
+      continue;
+    }
     if (got[key] !== undefined && got[key] !== value)
       throw new ScopeUsageError(`--${key} given twice`);
     got[key] = value;
   }
-  if (got.workspace === undefined && got.actor === undefined)
+  if (got.workspace === undefined && got.actor === undefined) {
+    if (grants.length)
+      throw new ScopeUsageError(
+        "--grant needs --workspace and --actor: a grant widens a scoped server",
+      );
     return { scope: null, rest };
+  }
   if (got.workspace === undefined)
     throw new ScopeUsageError(
       "--actor needs --workspace: a scoped server serves one workspace",
@@ -95,7 +127,35 @@ export function parseScopeFlags(argv: readonly string[]): {
       `--actor "${printable(got.actor)}" is not agent:<id> ` +
         "(the id: letters, digits, dots, dashes, underscores; at most 64)",
     );
-  return { scope: { workspace: got.workspace, actor: got.actor }, rest };
+  const widened = grants.filter((g) => g !== got.workspace);
+  return {
+    scope: {
+      workspace: got.workspace,
+      actor: got.actor,
+      ...(widened.length ? { grants: widened } : {}),
+    },
+    rest,
+  };
+}
+
+/**
+ * Null when every `--grant` is one the org config gives this agent
+ * (`agents.<id>.grants`), else the refusal. A grant is config in git,
+ * reviewed like code: a flag alone never widens a scope.
+ */
+export function checkGrants(
+  scope: McpScope,
+  agents: Pick<ResolvedAgentsConfig, "agents">,
+): string | null {
+  const id = scope.actor.slice("agent:".length);
+  const allowed = agents.agents[id]?.grants ?? [];
+  for (const g of scope.grants ?? [])
+    if (!allowed.includes(g))
+      return (
+        `--grant ${g}: ${scope.actor} has no such grant in agents.${id}.grants ` +
+        "of the org config; a grant is config, never a flag alone"
+      );
+  return null;
 }
 
 /** A value echoed back in an error: one printable line, bounded. */
@@ -103,7 +163,35 @@ function printable(v: string): string {
   return v.replace(/[^\x20-\x7e]/g, "?").slice(0, 80);
 }
 
-/** The refusal for a call that names `other`. */
+/**
+ * A path echoed back in an error: one printable line, never cut mid-name
+ * (0.3.0-dev.40, a consumer's 0.2.8 nit: printable's 80-character cap cut
+ * the filename). Up to `max` characters it is whole; a longer one keeps its
+ * start and its last segment whole, eliding the middle with "…".
+ */
+export function printablePath(v: string, max = 160): string {
+  const s = v.replace(/[^\x20-\x7e]/g, "?");
+  if (s.length <= max) return s;
+  const cut = s.lastIndexOf("/");
+  const tail = cut >= 0 ? s.slice(cut) : s;
+  // The last segment is kept whole whatever its length; the room left is
+  // shared between the path's start and the directories just before it.
+  const room = max - tail.length - 1;
+  if (room <= 0) return `…${tail}`;
+  const head = s.slice(0, Math.ceil(room / 2));
+  const end = s.length - tail.length;
+  const more = s.slice(end - (room - head.length), end);
+  return `${head}…${more}${tail}`;
+}
+
+/** "grants: a, b" or "no grants": what else the scope reaches. */
+function grantsNote(scope: McpScope): string {
+  return scope.grants?.length
+    ? `grants: ${scope.grants.join(", ")}`
+    : "no grants";
+}
+
+/** The refusal for a call that names `other`; it names the agent's grants. */
 export function otherWorkspace(
   tool: string,
   scope: McpScope,
@@ -111,7 +199,7 @@ export function otherWorkspace(
 ): ScopeRefusal {
   return new ScopeRefusal(
     `${tool}: this MCP server is scoped to workspace "${scope.workspace}" ` +
-      `(${scope.actor}); "${printable(other)}" is another workspace, so nothing was read or run.`,
+      `(${scope.actor}; ${grantsNote(scope)}); "${printable(other)}" is another workspace, so nothing was read or run.`,
   );
 }
 
@@ -125,9 +213,20 @@ export function pinWorkspace(
   scope: McpScope,
 ): Record<string, unknown> {
   const ws = args.workspace;
-  if (ws !== undefined && ws !== null && ws !== "" && ws !== scope.workspace)
+  if (ws === undefined || ws === null || ws === "")
+    return { ...args, workspace: scope.workspace };
+  if (!scopeWorkspaces(scope).includes(String(ws)))
     throw otherWorkspace(tool, scope, String(ws));
-  return { ...args, workspace: scope.workspace };
+  return { ...args, workspace: String(ws) };
+}
+
+/** The granted workspace `args` names, or null for the scope's own. */
+export function crossedWorkspace(
+  args: Record<string, unknown>,
+  scope: McpScope,
+): string | null {
+  const ws = args.workspace;
+  return typeof ws === "string" && ws && ws !== scope.workspace ? ws : null;
 }
 
 /** What /api/workspaces answers (the fields the scope reads). */
@@ -154,13 +253,20 @@ export function filterWorkspacesBody(
 ): Record<string, unknown> {
   const b = asRecord(body) as WorkspacesBody;
   const ws = scope.workspace;
+  const served = scopeWorkspaces(scope);
   const only = (v: unknown): Record<string, unknown> => {
     const r = asRecord(v);
-    return ws in r ? { [ws]: r[ws] } : {};
+    return Object.fromEntries(
+      served.filter((n) => n in r).map((n) => [n, r[n]]),
+    );
   };
   return {
-    active: Array.isArray(b.active) ? b.active.filter((n) => n === ws) : [],
-    ...(b.focus === ws ? { focus: ws } : {}),
+    active: Array.isArray(b.active)
+      ? b.active.filter((n) => served.includes(n as string))
+      : [],
+    ...(typeof b.focus === "string" && served.includes(b.focus)
+      ? { focus: b.focus }
+      : {}),
     workspaces: only(b.workspaces),
     ...(b.resolvedDirs !== undefined
       ? { resolvedDirs: only(b.resolvedDirs) }
@@ -168,7 +274,11 @@ export function filterWorkspacesBody(
     ...(b.codeWorkspacePaths !== undefined
       ? { codeWorkspacePaths: only(b.codeWorkspacePaths) }
       : {}),
-    scope: { workspace: ws, actor: scope.actor },
+    scope: {
+      workspace: ws,
+      actor: scope.actor,
+      ...(scope.grants?.length ? { grants: scope.grants } : {}),
+    },
   };
 }
 
@@ -198,23 +308,38 @@ export async function assertScopeExists(
   return body;
 }
 
+/** Throws unless the granted workspace `ws` exists in this distribution. */
+export async function assertGrantExists(
+  tool: string,
+  api: DenApi,
+  scope: McpScope,
+  ws: string,
+): Promise<void> {
+  const body = await api.get("/api/workspaces");
+  if (!(ws in asRecord(asRecord(body).workspaces)))
+    throw new ScopeRefusal(
+      `${tool}: ${scope.actor} has a grant for workspace "${printable(ws)}", which does not exist in this distribution; nothing was read or run.`,
+    );
+}
+
 /**
  * Tests run against the focused workspace (the web server has no workspace
  * argument for them): a scoped server runs or lists them only when that is
- * its own.
+ * its own or a granted one. Returns the focused workspace.
  */
 export async function assertScopeFocused(
   tool: string,
   api: DenApi,
   scope: McpScope,
-): Promise<void> {
+): Promise<string> {
   const focused = focusedOf(await api.get("/api/workspaces"));
-  if (focused !== scope.workspace)
-    throw new ScopeRefusal(
-      `${tool}: tests run against the focused workspace` +
-        `${focused ? ` ("${focused}")` : ""}, and this MCP server is scoped to ` +
-        `"${scope.workspace}". Focus "${scope.workspace}" first; nothing was read or run.`,
-    );
+  // A granted workspace that is focused is served too (and audited).
+  if (focused && scopeWorkspaces(scope).includes(focused)) return focused;
+  throw new ScopeRefusal(
+    `${tool}: tests run against the focused workspace` +
+      `${focused ? ` ("${focused}")` : ""}, and this MCP server is scoped to ` +
+      `"${scope.workspace}". Focus "${scope.workspace}" first; nothing was read or run.`,
+  );
 }
 
 /** The fields of an /api/services entry the scope checks read. */
@@ -272,6 +397,6 @@ export async function assertPathInScope(
     .map((r) => path.resolve(r));
   if (!roots.some((r) => target === r || target.startsWith(r + path.sep)))
     throw new ScopeRefusal(
-      `${tool}: ${printable(p)} is not inside a repo of workspace "${scope.workspace}", the only one this MCP server serves; nothing was read.`,
+      `${tool}: ${printablePath(p)} is not inside a repo of workspace "${scope.workspace}", the only one this MCP server serves; nothing was read.`,
     );
 }

package/src/ui/mcp/server.ts

@@ -11,6 +11,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { agentAuditHeaders } from "../../shared/agent-actor.js";
 import {
+  readAgentsConfig,
   readMcpConfig,
   type ResolvedMcpConfig,
 } from "../../shared/den-config.js";
@@ -22,7 +23,12 @@ import { createDenApi, type DenApi } from "./api.js";
 import { ownServer } from "../cli/server-identity.js";
 import { callTool, toolsFor, type ToolContext } from "./tools.js";
 import { plural } from "../../shared/plural.js";
-import { parseScopeFlags, ScopeUsageError, type McpScope } from "./scope.js";
+import {
+  checkGrants,
+  parseScopeFlags,
+  ScopeUsageError,
+  type McpScope,
+} from "./scope.js";
 
 export interface DenMcpOptions {
   cfg: ResolvedMcpConfig;
@@ -146,7 +152,7 @@ export const MCP_USAGE = (cli: string): string =>
     `Usage: ${cli} mcp [--port <web port>]`,
     `       ${cli} mcp --list`,
     `       ${cli} mcp --call <tool> ['<json args>']`,
-    `       ${cli} mcp --workspace <ws> --actor agent:<id> [...]`,
+    `       ${cli} mcp --workspace <ws> --actor agent:<id> [--grant <ws>…] [...]`,
     "",
     `An MCP server over stdio for agents, a client of the running web server`,
     `(\`${cli} web up\`; default port: config web.port). Read tools always;`,
@@ -160,6 +166,10 @@ export const MCP_USAGE = (cli: string): string =>
     "is recorded as agent:<id>. It binds cooperating agents only: the web",
     "server's HTTP API does not check the scope yet.",
     "",
+    "--grant <ws> (repeatable) also serves another workspace, only when the org",
+    "config's agents.<id>.grants lists it; each such call is recorded with both",
+    "workspaces. `agents start` passes an agent's grants for you.",
+    "",
     `Register it with your agents: ${cli} mcp clients, then ${cli} mcp connect <client> (or --all).`,
   ].join("\n");
 
@@ -269,6 +279,20 @@ export async function runMcp(rawArgv: string[]): Promise<void> {
     process.exitCode = 2;
     return;
   }
+  if (scope?.grants?.length) {
+    // A grant is config: a flag alone never widens a scope.
+    let refused: string | null;
+    try {
+      refused = checkGrants(scope, readAgentsConfig());
+    } catch (e) {
+      refused = (e as Error).message;
+    }
+    if (refused) {
+      process.stderr.write(`${cli} mcp: ${refused}\n`);
+      process.exitCode = 2;
+      return;
+    }
+  }
   let port = parsePort(argv);
   if (port === undefined) {
     try {
@@ -315,6 +339,7 @@ export async function runMcp(rawArgv: string[]): Promise<void> {
     `${cli} mcp: ${plural(toolsFor(cfg).length, "tool")} ` +
       `(${cfg.actions.length ? `actions: ${cfg.actions.join(", ")}` : "read only"}) → ${baseUrl}` +
       (scope ? ` · scoped to ${scope.workspace} as ${scope.actor}` : "") +
+      (scope?.grants?.length ? ` · grants: ${scope.grants.join(", ")}` : "") +
       "\n",
   );
 }

package/src/ui/mcp/tools.ts

@@ -35,10 +35,12 @@ import {
 } from "./guards.js";
 import {
   ScopeRefusal,
+  assertGrantExists,
   assertPathInScope,
   assertScopeExists,
   assertScopeFocused,
   assertServicesInScope,
+  crossedWorkspace,
   filterWorkspacesBody,
   pinWorkspace,
   type McpScope,
@@ -303,7 +305,12 @@ const READ_TOOLS: DenTool[] = [
     "The test modules of a pillar, and which repos (branch + SHA) they come from.",
     { pillar: z.enum(PILLARS) },
     async (a, { api, scope }) => {
-      if (scope) await assertScopeFocused("tests_available", api, scope);
+      if (scope)
+        await crossIfGranted(
+          { api, scope },
+          "tests_available",
+          await assertScopeFocused("tests_available", api, scope),
+        );
       return {
         modules: await api.get("/api/modules", { pillar: String(a.pillar) }),
         sources: await api.get("/api/test-sources", {
@@ -538,7 +545,12 @@ const ACTION_TOOLS: Record<McpAction, DenTool> = {
       const mode =
         pillar === "security" ? (str(a.mode) ?? "baseline") : undefined;
       assertRunTestsAllowed({ pillar, env, mode }, cfg);
-      if (scope) await assertScopeFocused("run_tests", api, scope);
+      if (scope)
+        await crossIfGranted(
+          { api, scope },
+          "run_tests",
+          await assertScopeFocused("run_tests", api, scope),
+        );
       if (pillar === "security") {
         for (const service of modules.length ? modules : [undefined]) {
           const plan = (await api.get("/api/security/plan", {
@@ -601,13 +613,17 @@ export function versionBefore(a: string, b: string): boolean {
   return false;
 }
 
-/** The running web server's version, or undefined when it reports none. */
-async function webServerVersion(api: DenApi): Promise<string | undefined> {
+/** The running web server's /api/server-info, or null when it has none. */
+async function readServerInfo(
+  api: DenApi,
+): Promise<Record<string, unknown> | null> {
   try {
-    const info = (await api.get("/api/server-info")) as { version?: unknown };
-    return typeof info?.version === "string" ? info.version : undefined;
+    const info = (await api.get("/api/server-info")) as unknown;
+    return info && typeof info === "object"
+      ? (info as Record<string, unknown>)
+      : null;
   } catch (e) {
-    if (e instanceof DenHttpError) return undefined;
+    if (e instanceof DenHttpError) return null;
     throw e;
   }
 }
@@ -621,11 +637,13 @@ async function notFoundMessage(
   e: DenHttpError,
   tool: string,
   ctx: ToolContext,
+  info: () => Promise<Record<string, unknown> | null>,
 ): Promise<string> {
   const plain = `Error: ${tool}: the web server answered 404 for ${e.method} ${e.path}: ${e.body}`;
   const since = ROUTE_SINCE[e.path];
   if (!since) return plain;
-  const version = await webServerVersion(ctx.api);
+  const v = (await info())?.version;
+  const version = typeof v === "string" ? v : undefined;
   if (version !== undefined && !versionBefore(version, since)) return plain;
   return (
     `web server is Den ${version ?? `< ${since}`}; ` +
@@ -664,6 +682,30 @@ async function reportRefusal(
   }
 }
 
+/**
+ * MD-2: when the web server runs an older engine than the one on disk (a
+ * pin upgraded Den under it), every failed call says so, naming both
+ * versions and the restart. Null when the engines agree or it can't tell.
+ */
+function staleEngineMessage(
+  tool: string,
+  ctx: ToolContext,
+  info: Record<string, unknown> | null,
+): string | null {
+  if (info?.engineStale !== true) return null;
+  const ver = (x: unknown) =>
+    x &&
+    typeof x === "object" &&
+    typeof (x as { version?: unknown }).version === "string"
+      ? (x as { version: string }).version
+      : "unknown";
+  return (
+    `Error: ${tool}: Den was updated to ${ver(info.onDisk)}, but the web server ` +
+    `is still running ${ver(info.loaded)}. Restart it: ${ctx.cli} web restart ` +
+    `(or your service restart).`
+  );
+}
+
 /**
  * A scoped server's arguments: the workspace exists (checked once per
  * server), and a tool that takes a workspace gets the scoped one; naming
@@ -680,9 +722,36 @@ async function scopeArgs(
     await assertScopeExists(ctx.api, scope);
     verifiedScopes.add(scope);
   }
-  return "workspace" in tool.shape
-    ? pinWorkspace(tool.name, args, scope)
-    : args;
+  if (!("workspace" in tool.shape)) return args;
+  const pinned = pinWorkspace(tool.name, args, scope);
+  const crossed = crossedWorkspace(pinned, scope);
+  if (crossed) {
+    await assertGrantExists(tool.name, ctx.api, scope, crossed);
+    await reportCrossWorkspace(ctx.api, tool.name, crossed);
+  }
+  return pinned;
+}
+
+/**
+ * A call into a granted workspace (AG-2a, §5b) is recorded before it runs,
+ * with both workspaces named: the server's entry takes the scoped one from
+ * the actor's headers and the target from this report.
+ */
+async function reportCrossWorkspace(
+  api: DenApi,
+  tool: string,
+  target: string,
+): Promise<void> {
+  await api.get("/api/activity", {}, "POST", { tool, crossWorkspace: target });
+}
+
+/** Report `ws` when it is a granted workspace, not the scope's own. */
+async function crossIfGranted(
+  ctx: { api: DenApi; scope: McpScope },
+  tool: string,
+  ws: string,
+): Promise<void> {
+  if (ws !== ctx.scope.workspace) await reportCrossWorkspace(ctx.api, tool, ws);
 }
 
 export async function callTool(
@@ -709,8 +778,21 @@ export async function callTool(
         text: redactSecrets(JSON.stringify(e.out, null, 2)),
         isError: true,
       };
+    // server-info is read lazily, once, and only after a call failed.
+    let infoRead: Promise<Record<string, unknown> | null> | null = null;
+    const info = () => (infoRead ??= readServerInfo(ctx.api).catch(() => null));
+    if (e instanceof DenHttpError) {
+      const stale = staleEngineMessage(name, ctx, await info());
+      if (stale)
+        return {
+          text: redactSecrets(
+            `${stale} (${e.method} ${e.path} answered ${e.status}: ${e.body})`,
+          ),
+          isError: true,
+        };
+    }
     if (e instanceof DenHttpError && e.status === 404) {
-      const text = await notFoundMessage(e, name, ctx).catch(
+      const text = await notFoundMessage(e, name, ctx, info).catch(
         (inner: Error) => `Error: ${inner.message}`,
       );
       return { text: redactSecrets(text), isError: true };

package/src/ui/server/appearance-prefs.ts

@@ -0,0 +1,95 @@
+/**
+ * Appearance preferences: the theme and mode this engineer chose. Stored in
+ * the user config as `appearance:` and served by /api/settings, like the
+ * graph prefs. A pure UI preference: changing it writes this block of
+ * config/local/user.yml and nothing else (no edge, services or restart).
+ */
+
+export type ModePref = "system" | "dark" | "light";
+
+export interface AppearancePrefs {
+  /**
+   * A theme id, or null to follow the org default (the org config's
+   * `brand.theme`, else den). A named theme is pinned even when it is the
+   * org default today: you keep it when the org changes `brand.theme`.
+   */
+  theme: string | null;
+  /** system follows prefers-color-scheme. */
+  mode: ModePref;
+}
+
+export const APPEARANCE_DEFAULTS: AppearancePrefs = {
+  theme: null,
+  mode: "system",
+};
+
+export const MODES: readonly ModePref[] = ["system", "dark", "light"];
+const THEME_ID = /^[a-z][a-z0-9-]{1,39}$/;
+
+const isObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * The stored block, normalised. A stored theme id is kept even when that
+ * theme is not installed now (resolution warns and falls back), so a theme
+ * that is briefly missing does not lose the preference.
+ */
+export function appearancePrefs(stored: unknown): AppearancePrefs {
+  const out: AppearancePrefs = { ...APPEARANCE_DEFAULTS };
+  if (!isObject(stored)) return out;
+  if (typeof stored.theme === "string" && THEME_ID.test(stored.theme))
+    out.theme = stored.theme;
+  if (MODES.includes(stored.mode as ModePref))
+    out.mode = stored.mode as ModePref;
+  return out;
+}
+
+/**
+ * Merge a POSTed (partial) block. `theme` must name an installed theme that
+ * validates; null or "" clears it ("Org default": follow the org); any bad
+ * field fails the whole patch.
+ *
+ * A theme picked by name is stored by name, even one that is the org
+ * default now (0.3.0-dev.11): that is a pin, and the menu shows it as one.
+ * Only "Org default" follows the org when it changes `brand.theme`.
+ */
+export function mergeAppearancePrefs(
+  current: AppearancePrefs,
+  patch: unknown,
+  isUsableTheme: (id: string) => boolean,
+): { ok: true; value: AppearancePrefs } | { ok: false; error: string } {
+  if (!isObject(patch))
+    return { ok: false, error: "appearance must be an object" };
+  const out: AppearancePrefs = { ...current };
+  for (const [key, v] of Object.entries(patch)) {
+    if (key === "mode") {
+      // null clears it to the default (0.3.0-dev.32), as theme's does.
+      if (v === null) out.mode = APPEARANCE_DEFAULTS.mode;
+      else if (!MODES.includes(v as ModePref))
+        return {
+          ok: false,
+          error: `appearance.mode must be one of ${MODES.map((m) => `"${m}"`).join(", ")}`,
+        };
+      else out.mode = v as ModePref;
+    } else if (key === "theme") {
+      if (v === null || v === "") out.theme = null;
+      else if (typeof v !== "string" || !THEME_ID.test(v) || !isUsableTheme(v))
+        return {
+          ok: false,
+          error: `appearance.theme: no valid installed theme "${String(v)}"`,
+        };
+      else out.theme = v;
+    } else return { ok: false, error: `unknown appearance setting "${key}"` };
+  }
+  return { ok: true, value: out };
+}
+
+/** What user.yml stores: only what differs from the defaults. */
+export function storedAppearance(
+  p: AppearancePrefs,
+): { theme?: string; mode?: ModePref } | undefined {
+  const out: { theme?: string; mode?: ModePref } = {};
+  if (p.theme) out.theme = p.theme;
+  if (p.mode !== APPEARANCE_DEFAULTS.mode) out.mode = p.mode;
+  return Object.keys(out).length ? out : undefined;
+}

package/src/ui/server/audit.ts

@@ -8,6 +8,7 @@
 import * as path from "path";
 import {
   actorLabel,
+  WORKSPACE_NAME_RE,
   type Actor,
   type AgentActor,
 } from "../../shared/agent-actor.js";
@@ -25,6 +26,11 @@ export interface AuditEntry {
   agent?: string;
   /** The workspace that scoped server is pinned to. */
   workspace?: string;
+  /**
+   * The other workspace a call reached under a grant (`agents.<id>.grants`,
+   * AG-2a); `workspace` is the agent's own.
+   */
+  targetWorkspace?: string;
   /** exec | run | sync, or the MCP tool name for a refused non-lifecycle call */
   verb: string;
   detail: string;
@@ -63,6 +69,7 @@ export function recordAction(
     outcome?: "refused";
     reason?: string;
     addresses?: string[];
+    targetWorkspace?: string;
   },
 ): AuditEntry {
   const entry: AuditEntry = {
@@ -78,6 +85,9 @@ export function recordAction(
           ...(actor.workspace ? { workspace: actor.workspace } : {}),
         }
       : {}),
+    ...(action.targetWorkspace
+      ? { targetWorkspace: action.targetWorkspace }
+      : {}),
     verb: action.verb,
     detail: action.detail,
     ...(action.outcome ? { outcome: action.outcome } : {}),
@@ -194,6 +204,31 @@ export function recordAgentRefusal(
   });
 }
 
+/**
+ * A scoped agent's call into a workspace it holds a grant for (AG-2a, AG
+ * spec §5b), reported by its MCP server before the call runs. Recorded
+ * with both workspaces: the agent's own (from its headers) and the target.
+ * Null, and nothing recorded, unless the actor is a scoped agent and the
+ * target is a well-formed workspace other than its own. `GET /api/activity
+ * ?address=workspace:<ws>` lists it under either workspace.
+ */
+export function recordCrossWorkspace(
+  actor: Actor,
+  report: { tool?: unknown; crossWorkspace?: unknown },
+): AuditEntry | null {
+  if (!actor?.agent || !actor.workspace) return null;
+  const target =
+    typeof report.crossWorkspace === "string" ? report.crossWorkspace : "";
+  if (!WORKSPACE_NAME_RE.test(target) || target === actor.workspace)
+    return null;
+  const tool = clean(report.tool, 64).replace(/[^A-Za-z0-9_]/g, "") || "tool";
+  return recordAction(actor, {
+    verb: tool,
+    detail: `in workspace ${target}, under a grant to ${actor.agent} of workspace ${actor.workspace}`,
+    targetWorkspace: target,
+  });
+}
+
 /**
  * The catalog repo a refused call's `path` is inside (manifest_validate), so
  * the refusal shows in that repo's activity: the repo whose checkout is the