🤖 feat: goal status board and agent-browser self-check for artifacts

- Goal status board: the host keeps `$XUM_SCRATCH_DIR/artifacts/goal.status.html` current at goal events (create, pause, resume, budget edits, completion) and continuation-turn starts
- `artifacts.capabilities` route and an agent-browser banner in the HTML viewer when the agent can check its own artifacts
- Artifact write helpers next to the read paths (host and runtime) for host-maintained files
- artifact_list description points agents at agent-browser for self-checks
- Codex review round 1 fixes: host artifact writer pins the real artifacts root and re-checks the opened file after rename, writers no longer mkdir -p, agent-browser probe uses the execution cwd and tool_env (trust in the cache key), cleared goal renders No active goal, per-workspace agent-browser answer, gh probes from the repo root, board follows the app theme (data-xum-theme), todo/plan changes re-render the board, only SUCCESS counts as passed, notify only on visible changes, tabular numerals
- Codex review round 2 fixes: goal observer key covers cost, turns and completion summary, finalize re-reads the durable goal and notifies only for the same goal, runtime board writes land in distinct wall-clock seconds
- Codex review round 3 fixes: the runtime board wait records the host time of the previous write and waits until that + 1000 ms instead of rounding to the next host second

---

_Generated with `xum` • Model: `anthropic:claude-opus-5-5` • Thinking: `high` • Cost: `$123.74`_

<!-- mux-attribution: model=anthropic:claude-opus-5-5 thinking=high costs=123.74 -->

Author: ThomasK33

src/browser/features/RightSidebar/ArtifactsTab/ArtifactViewer.test.tsx

@@ -2,7 +2,7 @@
 import "../../../../../tests/ui/dom";
 
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
-import { act, cleanup, fireEvent, render, waitFor } from "@testing-library/react";
+import { act, cleanup, fireEvent, render, renderHook, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { installDom } from "../../../../../tests/ui/dom";
 import { APIProvider, type APIClient } from "@/browser/contexts/API";
@@ -19,6 +19,7 @@ import { DESKTOP_ONLY_PREVIEW_NOTICE } from "./executableFrames";
 import { ArtifactsPanel } from "./ArtifactsPanel";
 import { ARTIFACT_TABLE_MAX_COLUMNS, ARTIFACT_TABLE_MAX_ROWS } from "./DataTable";
 import { JSON_TREE_MAX_NODES } from "./jsonData";
+import { useAgentBrowserAvailable } from "./useAgentBrowserAvailable";
 
 function ok(
   path: string,
@@ -39,6 +40,8 @@ function ok(
 let files: Record<string, ArtifactReadResult> = {};
 let selected = "";
 let readInputs: Array<{ path: string; maxBytes?: number | null }> = [];
+let agentBrowserAvailable: boolean | null = null;
+let capabilityRequests = 0;
 
 function Wrapper(props: { children: ReactNode }) {
   const api: TestApiOverrides<APIClient> = {
@@ -71,6 +74,10 @@ function Wrapper(props: { children: ReactNode }) {
             : { success: false as const, error: `Artifact not found: ${input.path}` }
         );
       },
+      capabilities: () => {
+        capabilityRequests++;
+        return Promise.resolve({ agentBrowserAvailable });
+      },
     },
   };
   return (
@@ -100,6 +107,8 @@ describe("ArtifactViewer renderers", () => {
       versions: {},
       getIsRosetta: () => Promise.resolve(false),
     };
+    agentBrowserAvailable = null;
+    capabilityRequests = 0;
   });
 
   afterEach(() => {
@@ -269,6 +278,56 @@ describe("ArtifactViewer renderers", () => {
     await waitFor(() => expect(view.queryByRole("dialog") == null).toBe(true));
   });
 
+  test("warns above HTML artifacts only when agent-browser is known to be missing", async () => {
+    const warning = "Not checked by the agent: agent-browser is not available on this runtime.";
+    for (const value of [true, null]) {
+      agentBrowserAvailable = value;
+      capabilityRequests = 0;
+      const view = renderArtifact("page.html", { "page.html": ok("page.html", "<p>hi</p>") });
+      await view.findByTestId("artifact-frame");
+      await waitFor(() => expect(capabilityRequests).toBeGreaterThan(0));
+      // Let the answer render before asserting the warning stays absent.
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      expect(view.queryByText(warning)).toBeNull();
+      cleanup();
+    }
+
+    agentBrowserAvailable = false;
+    const html = renderArtifact("page.html", { "page.html": ok("page.html", "<p>hi</p>") });
+    expect(await html.findByText(warning)).toBeTruthy();
+    expect(await html.findByTestId("artifact-frame")).toBeTruthy();
+    cleanup();
+
+    const markdown = renderArtifact("notes.md", { "notes.md": ok("notes.md", "# Notes") });
+    expect(await markdown.findByText("Notes")).toBeTruthy();
+    expect(markdown.queryByText(warning)).toBeNull();
+  });
+
+  test("an agent-browser answer for one workspace never shows for another", async () => {
+    // ws-a answers false; ws-b's request fails, which must read as unknown, not ws-a's false.
+    const client = createTestApiClient({
+      artifacts: {
+        capabilities: (input: { workspaceId: string }) =>
+          input.workspaceId === "ws-a"
+            ? Promise.resolve({ agentBrowserAvailable: false })
+            : Promise.reject(new Error("unreachable")),
+      },
+    } satisfies TestApiOverrides<APIClient>);
+    const hook = renderHook(
+      (props: { workspaceId: string }) => useAgentBrowserAvailable(props.workspaceId),
+      {
+        initialProps: { workspaceId: "ws-a" },
+        wrapper: (props: { children: ReactNode }) => (
+          <APIProvider client={client}>{props.children}</APIProvider>
+        ),
+      }
+    );
+    await waitFor(() => expect(hook.result.current).toBe(false));
+    hook.rerender({ workspaceId: "ws-b" });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(hook.result.current).toBeNull();
+  });
+
   test("resolves relative Markdown images through the artifacts API", async () => {
     const view = renderArtifact("notes/report.md", {
       "notes/report.md": ok("notes/report.md", "# R\n\n![chart](img/c.png)"),

src/browser/features/RightSidebar/ArtifactsTab/ArtifactViewer.tsx

@@ -1,3 +1,4 @@
+import type React from "react";
 import { Check, Copy, Download, ExternalLink } from "lucide-react";
 import { Mermaid } from "@/browser/features/Messages/Mermaid";
 import { useCopyToClipboard } from "@/browser/hooks/useCopyToClipboard";
@@ -14,7 +15,8 @@ import { JsonArtifact } from "./JsonArtifact";
 import { MarkdownArtifact } from "./MarkdownArtifact";
 import { canMountExecutableArtifactFrames, DESKTOP_ONLY_PREVIEW_NOTICE } from "./executableFrames";
 import { SandboxedArtifactFrame, type ArtifactFrameKey } from "./SandboxedArtifactFrame";
-import { Notice, SourceText } from "./SourceText";
+import { Notice, NoteBar, SourceText } from "./SourceText";
+import { useAgentBrowserAvailable } from "./useAgentBrowserAvailable";
 
 // Every renderer here goes through React elements, so artifact content (agent-written,
 // therefore untrusted) is always escaped. HTML and SVG only ever render inside
@@ -81,6 +83,28 @@ function PdfArtifact(props: { result: Extract<ArtifactReadResult, { status: "ok"
   );
 }
 
+export const AGENT_BROWSER_MISSING_WARNING =
+  "Not checked by the agent: agent-browser is not available on this runtime.";
+
+/**
+ * HTML and SVG are the artifacts the agent can check with agent-browser; when the runtime has
+ * none, say so above the frame (null means unknown, which shows nothing).
+ */
+function SandboxedArtifactWithCheckNotice(
+  props: React.ComponentProps<typeof SandboxedArtifactFrame>
+) {
+  const agentBrowserAvailable = useAgentBrowserAvailable(props.workspaceId);
+  // One stable tree, so the answer arriving never remounts (reloads) the frame.
+  return (
+    <div className="flex h-full min-h-0 flex-col">
+      {agentBrowserAvailable === false && <NoteBar>{AGENT_BROWSER_MISSING_WARNING}</NoteBar>}
+      <div className="min-h-0 flex-1">
+        <SandboxedArtifactFrame {...props} />
+      </div>
+    </div>
+  );
+}
+
 export function ArtifactViewer(props: {
   result: ArtifactReadResult;
   workspaceId: string;
@@ -134,7 +158,7 @@ export function ArtifactViewer(props: {
         return <SourceText content={result.content} note={DESKTOP_ONLY_PREVIEW_NOTICE} />;
       }
       return (
-        <SandboxedArtifactFrame
+        <SandboxedArtifactWithCheckNotice
           workspaceId={props.workspaceId}
           path={result.path}
           kind={result.kind}

src/browser/features/RightSidebar/ArtifactsTab/artifactBridge.test.ts

@@ -68,12 +68,19 @@ function runBridgeScript() {
       listeners.set(type, listener);
     },
   };
+  // The script mirrors the theme onto the root element (data-xum-theme).
+  const fakeDocument = {
+    documentElement: { setAttribute: () => undefined },
+    addEventListener: () => undefined,
+  };
   // eslint-disable-next-line @typescript-eslint/no-implied-eval -- runs our own generated script
-  const run = new Function("window", "CustomEvent", buildArtifactBridgeScript("dark")) as (
-    window: unknown,
-    customEvent: unknown
-  ) => void;
-  run(fakeWindow, class {});
+  const run = new Function(
+    "window",
+    "document",
+    "CustomEvent",
+    buildArtifactBridgeScript("dark")
+  ) as (window: unknown, document: unknown, customEvent: unknown) => void;
+  run(fakeWindow, fakeDocument, class {});
   const keydown = (key: string, target: unknown, shiftKey = false) =>
     listeners.get("keydown")?.({
       key,
@@ -114,4 +121,45 @@ describe("buildArtifactBridgeScript", () => {
     // Bun's transpiler throws on a syntax error, which is all this needs to prove.
     expect(() => new Bun.Transpiler({ loader: "js" }).transformSync(script)).not.toThrow();
   });
+
+  test("mirrors the app theme into data-xum-theme for script-free artifacts", () => {
+    const attributes = new Map<string, string>();
+    type FakeMessageListener = (event: { source: unknown; data: unknown }) => void;
+    const listeners: FakeMessageListener[] = [];
+    const parent = {};
+    const fakeWindow = {
+      parent,
+      addEventListener: (type: string, listener: FakeMessageListener) => {
+        if (type === "message") listeners.push(listener);
+      },
+      dispatchEvent: () => true,
+    };
+    const fakeDocument = {
+      documentElement: {
+        setAttribute: (name: string, value: string) => attributes.set(name, value),
+      },
+    };
+    class FakeCustomEvent {
+      constructor(
+        readonly type: string,
+        readonly init: unknown
+      ) {}
+    }
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval -- runs the generated frame script
+    const run = new Function(
+      "window",
+      "document",
+      "CustomEvent",
+      buildArtifactBridgeScript("light")
+    ) as (window: unknown, document: unknown, customEvent: unknown) => void;
+    run(fakeWindow, fakeDocument, FakeCustomEvent);
+    expect(attributes.get("data-xum-theme")).toBe("light");
+
+    const send = (data: unknown, source: unknown = parent) =>
+      listeners.forEach((listener) => listener({ source, data }));
+    send({ xumArtifact: 1, type: "theme", theme: "dark" }, {});
+    expect(attributes.get("data-xum-theme")).toBe("light");
+    send({ xumArtifact: 1, type: "theme", theme: "dark" });
+    expect(attributes.get("data-xum-theme")).toBe("dark");
+  });
 });

src/browser/features/RightSidebar/ArtifactsTab/artifactBridge.ts

@@ -107,6 +107,8 @@ export function postArtifactTheme(frameWindow: Window | null | undefined, theme:
  * Source of the inline <script> injected as the frame's first script (inline, so the CSP's
  * 'unsafe-inline' allows it). It forwards Escape and Shift+F to the host and exposes a
  * read-only `window.xum.theme`, updated from theme messages, plus a `xumthemechange` event.
+ * It also mirrors the theme into `data-xum-theme` on the root element, so plain CSS (the goal
+ * status board, which has no scripts) can follow the app theme instead of the OS preference.
  * Only the initial theme is interpolated, and only as a JSON string literal.
  */
 export function buildArtifactBridgeScript(initialTheme: ArtifactTheme): string {
@@ -117,12 +119,18 @@ export function buildArtifactBridgeScript(initialTheme: ArtifactTheme): string {
   var api = {};
   Object.defineProperty(api, "theme", { enumerable: true, get: function () { return theme; } });
   Object.defineProperty(window, "xum", { value: Object.freeze(api) });
+  function applyThemeAttribute() {
+    var root = document.documentElement;
+    if (root) root.setAttribute("data-xum-theme", theme);
+  }
+  applyThemeAttribute();
   window.addEventListener("message", function (event) {
     if (event.source !== host) return;
     var data = event.data;
     if (!data || typeof data !== "object" || data.xumArtifact !== ${ARTIFACT_BRIDGE_VERSION}) return;
     if (data.type === "theme" && (data.theme === "dark" || data.theme === "light")) {
       theme = data.theme;
+      applyThemeAttribute();
       window.dispatchEvent(new CustomEvent("xumthemechange", { detail: { theme: theme } }));
     }
   });

src/browser/features/RightSidebar/ArtifactsTab/useAgentBrowserAvailable.ts

@@ -0,0 +1,47 @@
+import { useEffect, useState } from "react";
+import { useAPI, type APIClient } from "@/browser/contexts/API";
+
+/**
+ * Last answer per API client and workspace. The viewer remounts on every file change, so a
+ * fresh mount starts from the last answer instead of flashing the warning in and out.
+ */
+const lastKnown = new WeakMap<APIClient, Map<string, boolean | null>>();
+
+interface Answer {
+  api: APIClient;
+  workspaceId: string;
+  value: boolean | null;
+}
+
+/**
+ * Whether the agent can look at its own HTML artifacts (`agent-browser` on the runtime's PATH).
+ * null while unknown, including when the probe or the request failed.
+ */
+export function useAgentBrowserAvailable(workspaceId: string): boolean | null {
+  const { api } = useAPI();
+  // The answer remembers which (api, workspace) it is for: after either changes, an answer for
+  // the old pair must not show (a failed request for the new pair would otherwise keep it).
+  const [answer, setAnswer] = useState<Answer | null>(null);
+  useEffect(() => {
+    if (!api) return;
+    let cancelled = false;
+    // Promise.resolve() first, so a client without the route rejects instead of throwing here.
+    Promise.resolve()
+      .then(() => api.artifacts.capabilities({ workspaceId }))
+      .then((result) => {
+        const perClient = lastKnown.get(api) ?? new Map<string, boolean | null>();
+        perClient.set(workspaceId, result.agentBrowserAvailable);
+        lastKnown.set(api, perClient);
+        if (!cancelled) setAnswer({ api, workspaceId, value: result.agentBrowserAvailable });
+      })
+      .catch(() => {
+        // Unknown: no warning.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [api, workspaceId]);
+  if (!api) return null;
+  if (answer?.api === api && answer.workspaceId === workspaceId) return answer.value;
+  return lastKnown.get(api)?.get(workspaceId) ?? null;
+}

src/browser/stories/mocks/orpc.ts

@@ -204,7 +204,12 @@ export interface MockORPCClientOptions {
   /** Optional file contents for memory.read keyed by virtual path. */
   memoryFileContents?: Map<string, string>;
   /** Artifacts tab: listing for artifacts.list and read results keyed by relative path. */
-  artifacts?: { listing: ArtifactListing; files: Record<string, ArtifactReadResult> };
+  artifacts?: {
+    listing: ArtifactListing;
+    files: Record<string, ArtifactReadResult>;
+    /** artifacts.capabilities answer; omitted means unknown (null). */
+    agentBrowserAvailable?: boolean | null;
+  };
   /** Initial updater status for update.onStatus (About dialog stories). */
   updateStatus?: UpdateStatus;
   /** Release channel for update.getChannel. */
@@ -2192,6 +2197,8 @@ export function createMockORPCClient(options: MockORPCClientOptions = {}): APICl
             : { success: false as const, error: `Artifact not found: ${input.path}` }
         );
       },
+      capabilities: () =>
+        Promise.resolve({ agentBrowserAvailable: artifacts.agentBrowserAvailable ?? null }),
     },
     // Memory curation surfaces (Memory tab / Settings → Memory). Backed by
     // the `memoryFiles` option; mutations update the in-memory set so

src/common/orpc/schemas/api.ts

@@ -61,7 +61,11 @@ import {
   MemoryFileInfoSchema,
   MemorySaveErrorSchema,
 } from "./memory";
-import { ArtifactListingSchema, ArtifactReadResultSchema } from "./artifacts";
+import {
+  ArtifactCapabilitiesSchema,
+  ArtifactListingSchema,
+  ArtifactReadResultSchema,
+} from "./artifacts";
 import { ResultSchema } from "./result";
 import { SshPromptEventSchema, SshPromptResponseInputSchema } from "./ssh";
 import {
@@ -1293,6 +1297,11 @@ export const artifacts = {
     }),
     output: ResultSchema(ArtifactReadResultSchema, z.string()),
   },
+  /** Runtime tooling probes (cached per workspace); never fails, null means unknown. */
+  capabilities: {
+    input: z.object({ workspaceId: z.string() }),
+    output: ArtifactCapabilitiesSchema,
+  },
 };
 
 /**

src/common/orpc/schemas/artifacts.ts

@@ -57,3 +57,12 @@ export const ArtifactReadResultSchema = z.discriminatedUnion("status", [
   z.object({ status: z.literal("binary"), ...ArtifactFileMetaSchema }),
 ]);
 export type ArtifactReadResult = z.infer<typeof ArtifactReadResultSchema>;
+
+export const ArtifactCapabilitiesSchema = z.object({
+  /**
+   * Whether `agent-browser` is on the runtime's PATH, so the agent can look at its own HTML
+   * artifacts. null when not probed yet or the probe failed.
+   */
+  agentBrowserAvailable: z.boolean().nullable(),
+});
+export type ArtifactCapabilities = z.infer<typeof ArtifactCapabilitiesSchema>;

src/common/utils/tools/toolDefinitions.ts

@@ -3319,6 +3319,8 @@ export const TOOL_DEFINITIONS = {
       "HTML (.html) runs in a sandbox with no network: inline your JS/CSS or reference files next to it by relative path; scripts may also load from cdnjs, unpkg, jsDelivr (/npm/), code.jquery.com and cdn.tailwindcss.com if the user allows it. Send no secrets into HTML artifacts. " +
       'To show JSON as a table, write {"$xum": "table", "columns": ["name", "value"], "rows": [{"name": "a", "value": 1}]}; "columns" is optional and each row is an object keyed by column or an array of cells. ' +
       "Files over 10 MB are listed but not previewed. " +
+      "After writing an HTML artifact, if `agent-browser` is available, open file://$XUM_SCRATCH_DIR/artifacts/<file> at phone (390px) and desktop widths, take screenshots, and attach them to yourself with attach_file to catch broken layouts. " +
+      "That file:// page has no sandbox or CSP, so CDN-loaded content can look different than in the Artifacts tab. " +
       "Update a file in place to update its artifact. Each workspace has its own folder, so a sub-agent's artifacts show in the sub-agent workspace, not its parent's. " +
       "Call this tool to see what already exists, for example after a context reset.",
     schema: z.object({}).strict(),

src/node/orpc/router.ts

@@ -31,7 +31,11 @@ import {
 } from "@/node/services/agentPlugins/workspacePluginOperations";
 import { handlerGen } from "@orpc/experimental-effect";
 import { Effect } from "effect";
-import { listArtifacts, readArtifact } from "@/node/services/artifactsOperations";
+import {
+  getArtifactsCapabilities,
+  listArtifacts,
+  readArtifact,
+} from "@/node/services/artifactsOperations";
 import {
   assertMemoryEnabled,
   consolidateMemoryEffect,
@@ -1522,6 +1526,10 @@ export const router = (authToken?: string) => {
         .input(schemas.artifacts.read.input)
         .output(schemas.artifacts.read.output)
         .handler(({ context, input, signal }) => readArtifact(context, input, signal)),
+      capabilities: t
+        .input(schemas.artifacts.capabilities.input)
+        .output(schemas.artifacts.capabilities.output)
+        .handler(({ context, input }) => getArtifactsCapabilities(context, input)),
     },
     // Memory handlers run Effect generators via handlerGen (client aborts
     // interrupt the fiber); the wire contracts are unchanged.