feat(FN-4640): complete Step 6 — dashboard sandbox audit surface

Fusion-Task-Id: FN-4640
Fusion-Task-Lineage: 4a91265f-1714-4854-b08d-7ddb06074253

packages/dashboard/README.md

@@ -1010,7 +1010,7 @@ interface RunAuditResponse {
 ```typescript
 interface RunTimelineResponse {
   run: { id, agentId, startedAt, endedAt?, status, taskId? };
-  auditByDomain: { database: [], git: [], filesystem: [] };
+  auditByDomain: { database: [], git: [], filesystem: [], sandbox: [] };
   counts: { auditEvents: number; logEntries: number };
   timeline: TimelineEntry[];
 }

packages/dashboard/app/__tests__/api-missions.test.ts

@@ -669,7 +669,7 @@ describe("fetchAgentRunTimeline", () => {
   it("fetches run timeline with correct URL encoding", async () => {
     const mockResponse = {
       run: { id: "run-001", agentId: "agent-001", startedAt: "2026-01-01T00:00:00Z", status: "active" },
-      auditByDomain: { database: [], git: [], filesystem: [] },
+      auditByDomain: { database: [], git: [], filesystem: [], sandbox: [] },
       counts: { auditEvents: 0, logEntries: 0 },
       timeline: [],
     };
@@ -687,7 +687,7 @@ describe("fetchAgentRunTimeline", () => {
   it("passes projectId as query param", async () => {
     const mockResponse = {
       run: { id: "run-001", agentId: "agent-001", startedAt: "2026-01-01T00:00:00Z", status: "active" },
-      auditByDomain: { database: [], git: [], filesystem: [] },
+      auditByDomain: { database: [], git: [], filesystem: [], sandbox: [] },
       counts: { auditEvents: 0, logEntries: 0 },
       timeline: [],
     };
@@ -704,7 +704,7 @@ describe("fetchAgentRunTimeline", () => {
   it("includes options in query string", async () => {
     const mockResponse = {
       run: { id: "run-001", agentId: "agent-001", startedAt: "2026-01-01T00:00:00Z", status: "active" },
-      auditByDomain: { database: [], git: [], filesystem: [] },
+      auditByDomain: { database: [], git: [], filesystem: [], sandbox: [] },
       counts: { auditEvents: 0, logEntries: 0 },
       timeline: [],
     };
@@ -734,7 +734,7 @@ describe("fetchAgentRunTimeline", () => {
   it("throws on 400 for blank runId before calling fetch", async () => {
     globalThis.fetch = vi.fn().mockReturnValue(mockFetchResponse(true, {
       run: { id: "run-001", agentId: "agent-001", startedAt: "2026-01-01T00:00:00Z", status: "active" },
-      auditByDomain: { database: [], git: [], filesystem: [] },
+      auditByDomain: { database: [], git: [], filesystem: [], sandbox: [] },
       counts: { auditEvents: 0, logEntries: 0 },
       timeline: [],
     }));

packages/dashboard/app/api/legacy.ts

@@ -5021,7 +5021,7 @@ export function stopAgentRun(
 // ── Run-Audit & Timeline API ────────────────────────────────────────────────
 
 /** Valid domain filters for run-audit queries. */
-export type RunAuditDomainFilter = "database" | "git" | "filesystem";
+export type RunAuditDomainFilter = "database" | "git" | "filesystem" | "sandbox";
 
 /** Filter options for run-audit queries. */
 export interface RunAuditFilters {
@@ -5042,7 +5042,7 @@ export interface NormalizedRunAuditEvent {
   id: string;
   timestamp: string;
   taskId?: string;
-  domain: "database" | "git" | "filesystem";
+  domain: "database" | "git" | "filesystem" | "sandbox";
   mutationType: string;
   target: string;
   summary: string;
@@ -5086,6 +5086,7 @@ export interface RunTimelineResponse {
     database: NormalizedRunAuditEvent[];
     git: NormalizedRunAuditEvent[];
     filesystem: NormalizedRunAuditEvent[];
+    sandbox: NormalizedRunAuditEvent[];
   };
   counts: {
     auditEvents: number;

packages/dashboard/src/__tests__/routes-agent-runs.test.ts

@@ -945,6 +945,7 @@ describe("Agent runs routes (with HeartbeatMonitor)", () => {
       expect(Array.isArray(response.body.auditByDomain.database)).toBe(true);
       expect(Array.isArray(response.body.auditByDomain.git)).toBe(true);
       expect(Array.isArray(response.body.auditByDomain.filesystem)).toBe(true);
+      expect(Array.isArray(response.body.auditByDomain.sandbox)).toBe(true);
       expect(response.body.auditByDomain.database.length).toBe(1);
       expect(response.body.counts.auditEvents).toBe(1);
       expect(response.body.counts.logEntries).toBe(2);
@@ -994,6 +995,7 @@ describe("Agent runs routes (with HeartbeatMonitor)", () => {
       expect(response.body.auditByDomain.database).toEqual([]);
       expect(response.body.auditByDomain.git).toEqual([]);
       expect(response.body.auditByDomain.filesystem).toEqual([]);
+      expect(response.body.auditByDomain.sandbox).toEqual([]);
       expect(response.body.counts.auditEvents).toBe(0);
       expect(response.body.counts.logEntries).toBe(0);
       expect(response.body.timeline).toEqual([]);
@@ -1031,6 +1033,15 @@ describe("Agent runs routes (with HeartbeatMonitor)", () => {
           mutationType: "file:write",
           target: "src/main.ts",
         },
+        {
+          id: "audit-sandbox",
+          timestamp: "2026-01-01T00:04:00.000Z",
+          agentId: "agent-001",
+          runId: "run-001",
+          domain: "sandbox",
+          mutationType: "sandbox:run",
+          target: "native",
+        },
       ];
       mockGetRunAuditEvents.mockReturnValue(mockAuditEvents);
       store.getAgentLogsByTimeRange = vi.fn().mockResolvedValue([]);
@@ -1041,7 +1052,8 @@ describe("Agent runs routes (with HeartbeatMonitor)", () => {
       expect(response.body.auditByDomain.database.length).toBe(1);
       expect(response.body.auditByDomain.git.length).toBe(1);
       expect(response.body.auditByDomain.filesystem.length).toBe(1);
-      expect(response.body.counts.auditEvents).toBe(3);
+      expect(response.body.auditByDomain.sandbox.length).toBe(1);
+      expect(response.body.counts.auditEvents).toBe(4);
     });
 
     it("returns 400 for blank runId (URL-encoded space)", async () => {

packages/dashboard/src/__tests__/routes-sandbox-audit.test.ts

@@ -0,0 +1,90 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { request } from "../test-request.js";
+
+const mockGetRunDetail = vi.fn();
+const mockGetRunAuditEvents = vi.fn();
+
+vi.mock("@fusion/core", () => ({
+  AgentStore: class MockAgentStore {
+    init = vi.fn().mockResolvedValue(undefined);
+    getRunDetail = mockGetRunDetail;
+  },
+  ChatStore: class MockChatStore {
+    init = vi.fn().mockResolvedValue(undefined);
+  },
+}));
+
+vi.mock("../project-store-resolver.js", () => ({
+  getOrCreateProjectStore: vi.fn(),
+}));
+
+class MockStore {
+  getRunAuditEvents = mockGetRunAuditEvents;
+  getAgentLogsByTimeRange = vi.fn().mockResolvedValue([]);
+  getMutationsForRun = vi.fn().mockResolvedValue([]);
+  getRootDir() {
+    return "/tmp/fn-4640-test";
+  }
+  getFusionDir() {
+    return "/tmp/fn-4640-test/.fusion";
+  }
+}
+
+function mockRun() {
+  return {
+    id: "run-001",
+    agentId: "agent-001",
+    startedAt: "2026-01-01T00:00:00.000Z",
+    endedAt: null,
+    status: "active",
+    contextSnapshot: { taskId: "FN-001" },
+  };
+}
+
+describe("sandbox run-audit route behavior", () => {
+  let app: ReturnType<typeof import("../server.js").createServer>;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    const { createServer } = await import("../server.js");
+    app = createServer(new MockStore() as any);
+    mockGetRunDetail.mockResolvedValue(mockRun());
+    mockGetRunAuditEvents.mockReturnValue([]);
+  });
+
+  it("accepts domain=sandbox filter", async () => {
+    const response = await request(app, "GET", "/api/agents/agent-001/runs/run-001/audit?domain=sandbox");
+    expect(response.status).toBe(200);
+    expect(mockGetRunAuditEvents).toHaveBeenCalledWith(expect.objectContaining({ domain: "sandbox" }));
+  });
+
+  it("rejects invalid domain with updated four-domain message", async () => {
+    const response = await request(app, "GET", "/api/agents/agent-001/runs/run-001/audit?domain=nope");
+    expect(response.status).toBe(400);
+    expect(response.body.error).toContain("domain must be one of: database, git, filesystem, sandbox");
+  });
+
+  it("normalizes sandbox events with Sandbox-prefixed summary and timeline bucket", async () => {
+    mockGetRunAuditEvents.mockReturnValue([
+      {
+        id: "audit-1",
+        timestamp: "2026-01-01T00:01:00.000Z",
+        agentId: "agent-001",
+        runId: "run-001",
+        domain: "sandbox",
+        mutationType: "sandbox:run",
+        target: "native",
+        taskId: "FN-001",
+      },
+    ]);
+
+    const auditResponse = await request(app, "GET", "/api/agents/agent-001/runs/run-001/audit");
+    expect(auditResponse.status).toBe(200);
+    expect(auditResponse.body.events[0].domain).toBe("sandbox");
+    expect(auditResponse.body.events[0].summary.startsWith("Sandbox")).toBe(true);
+
+    const timelineResponse = await request(app, "GET", "/api/agents/agent-001/runs/run-001/timeline");
+    expect(timelineResponse.status).toBe(200);
+    expect(timelineResponse.body.auditByDomain.sandbox).toHaveLength(1);
+  });
+});

packages/dashboard/src/routes.ts

@@ -540,7 +540,7 @@ function sanitizeOverlapIgnorePaths(value: unknown): string[] | undefined {
 // ── Run-Audit Timeline Types & Helpers ─────────────────────────────────────
 
 /** Valid domain filters for run-audit queries. */
-export type RunAuditDomainFilter = "database" | "git" | "filesystem";
+export type RunAuditDomainFilter = "database" | "git" | "filesystem" | "sandbox";
 
 /** Filter options for run-audit queries. */
 export interface RunAuditQueryFilters {
@@ -567,8 +567,8 @@ export interface NormalizedRunAuditEvent {
   timestamp: string;
   /** Task ID associated with this event (if applicable) */
   taskId?: string;
-  /** Domain category: database, git, or filesystem */
-  domain: "database" | "git" | "filesystem";
+  /** Domain category: database, git, filesystem, or sandbox */
+  domain: "database" | "git" | "filesystem" | "sandbox";
   /** Type of mutation (e.g., "task:update", "git:commit", "file:write") */
   mutationType: string;
   /** Target of the mutation (e.g., task ID, file path, branch name) */
@@ -635,6 +635,7 @@ export interface RunTimelineResponse {
     database: NormalizedRunAuditEvent[];
     git: NormalizedRunAuditEvent[];
     filesystem: NormalizedRunAuditEvent[];
+    sandbox: NormalizedRunAuditEvent[];
   };
   /** Count metadata */
   counts: {
@@ -666,8 +667,8 @@ function parseRunAuditFilters(query: Record<string, unknown>): RunAuditQueryFilt
       throw new ApiError(400, "domain must be a string");
     }
     const domain = query.domain.toLowerCase();
-    if (domain !== "database" && domain !== "git" && domain !== "filesystem") {
-      throw new ApiError(400, "domain must be one of: database, git, filesystem");
+    if (domain !== "database" && domain !== "git" && domain !== "filesystem" && domain !== "sandbox") {
+      throw new ApiError(400, "domain must be one of: database, git, filesystem, sandbox");
     }
     filters.domain = domain as RunAuditDomainFilter;
   }
@@ -759,6 +760,9 @@ function generateAuditSummary(
     case "filesystem":
       parts.push("FS");
       break;
+    case "sandbox":
+      parts.push("Sandbox");
+      break;
     default:
       parts.push(domain);
   }

packages/dashboard/src/routes/register-agent-runtime-routes.ts

@@ -23,7 +23,7 @@ interface AgentRuntimeRouteDeps {
   runExcerptToAgentLogs: (run: import("@fusion/core").AgentHeartbeatRun) => import("@fusion/core").AgentLogEntry[];
   parseRunAuditFilters: (query: Record<string, unknown>) => {
     taskId?: string;
-    domain?: "database" | "git" | "filesystem";
+    domain?: "database" | "git" | "filesystem" | "sandbox";
     startTime?: string;
     endTime?: string;
     limit?: number;
@@ -1442,7 +1442,7 @@ export function registerAgentRuntimeRoutes(ctx: ApiRoutesContext, deps: AgentRun
    *
    * Query params:
    *   - taskId: Filter by task ID
-   *   - domain: Filter by domain (database, git, filesystem)
+   *   - domain: Filter by domain (database, git, filesystem, sandbox)
    *   - startTime: Start of time range (ISO-8601)
    *   - endTime: End of time range (ISO-8601)
    *   - limit: Maximum events to return (default 100, max 1000)
@@ -1525,7 +1525,7 @@ export function registerAgentRuntimeRoutes(ctx: ApiRoutesContext, deps: AgentRun
    *
    * Query params:
    *   - taskId: Override task ID for audit filtering (defaults to run's contextSnapshot.taskId)
-   *   - domain: Filter audit events by domain (database, git, filesystem)
+   *   - domain: Filter audit events by domain (database, git, filesystem, sandbox)
    *   - startTime: Start of time range (ISO-8601)
    *   - endTime: End of time range (ISO-8601)
    *   - includeLogs: Whether to include agent logs (default true)
@@ -1590,6 +1590,7 @@ export function registerAgentRuntimeRoutes(ctx: ApiRoutesContext, deps: AgentRun
         database: [],
         git: [],
         filesystem: [],
+        sandbox: [],
       };
 
       for (const event of normalizedAuditEvents) {
@@ -1599,6 +1600,8 @@ export function registerAgentRuntimeRoutes(ctx: ApiRoutesContext, deps: AgentRun
           auditByDomain.git.push(event);
         } else if (event.domain === "filesystem") {
           auditByDomain.filesystem.push(event);
+        } else if (event.domain === "sandbox") {
+          auditByDomain.sandbox.push(event);
         }
       }
 

packages/engine/src/__tests__/auto-recovery-contamination.test.ts

@@ -44,7 +44,7 @@ describe("ContaminationAutoRecoveryHandler", () => {
 
   it("mode off does not call handler", async () => {
     const issueRetry = vi.fn();
-    const dispatcher = new AutoRecoveryDispatcher({ taskStore: {} as any, auditEmitter: { database: vi.fn(), git: vi.fn(), filesystem: vi.fn() }, handlers: { issueRetry } });
+    const dispatcher = new AutoRecoveryDispatcher({ taskStore: {} as any, auditEmitter: { database: vi.fn(), git: vi.fn(), filesystem: vi.fn(), sandbox: vi.fn() }, handlers: { issueRetry } });
     const decision = await dispatcher.dispatch({ class: "branch-cross-contamination", taskId: "FN-1", pausedReason: "branch-cross-contamination" }, { task: baseTask, retryCount: 0, settings: { mode: "off", maxRetries: 3 } });
     expect(decision.action).toBe("pause");
     expect(issueRetry).not.toHaveBeenCalled();

packages/engine/src/__tests__/auto-recovery.test.ts

@@ -8,7 +8,7 @@ function createDispatcher() {
   const database = vi.fn(async () => {});
   const dispatcher = new AutoRecoveryDispatcher({
     taskStore: {} as never,
-    auditEmitter: { database, git: vi.fn(), filesystem: vi.fn() },
+    auditEmitter: { database, git: vi.fn(), filesystem: vi.fn(), sandbox: vi.fn() },
   });
   return { dispatcher, database };
 }

packages/engine/src/__tests__/reliability-interactions/auto-recovery-contamination.test.ts

@@ -9,7 +9,7 @@ describe("reliability interaction: contamination auto-recovery precedence", () =
     const issueRetry = vi.fn();
     const dispatcher = new AutoRecoveryDispatcher({
       taskStore: {} as never,
-      auditEmitter: { database: vi.fn(async () => {}), git: vi.fn(), filesystem: vi.fn() },
+      auditEmitter: { database: vi.fn(async () => {}), git: vi.fn(), filesystem: vi.fn(), sandbox: vi.fn() },
       handlers: { issueRetry },
     });
 
@@ -38,7 +38,7 @@ describe("reliability interaction: contamination auto-recovery precedence", () =
     const issueRetry = vi.fn(async () => {});
     const dispatcher = new AutoRecoveryDispatcher({
       taskStore: {} as never,
-      auditEmitter: { database: vi.fn(async () => {}), git: vi.fn(), filesystem: vi.fn() },
+      auditEmitter: { database: vi.fn(async () => {}), git: vi.fn(), filesystem: vi.fn(), sandbox: vi.fn() },
       handlers: { issueRetry },
     });
 
@@ -60,7 +60,7 @@ describe("reliability interaction: contamination auto-recovery precedence", () =
   it("mode off and destructive ambiguity preserve pause", () => {
     const dispatcher = new AutoRecoveryDispatcher({
       taskStore: {} as never,
-      auditEmitter: { database: vi.fn(async () => {}), git: vi.fn(), filesystem: vi.fn() },
+      auditEmitter: { database: vi.fn(async () => {}), git: vi.fn(), filesystem: vi.fn(), sandbox: vi.fn() },
       handlers: { issueRetry: vi.fn() },
     });
 
@@ -88,7 +88,7 @@ describe("reliability interaction: contamination auto-recovery precedence", () =
   it("retry budget exhaustion pauses on subsequent event", () => {
     const dispatcher = new AutoRecoveryDispatcher({
       taskStore: {} as never,
-      auditEmitter: { database: vi.fn(async () => {}), git: vi.fn(), filesystem: vi.fn() },
+      auditEmitter: { database: vi.fn(async () => {}), git: vi.fn(), filesystem: vi.fn(), sandbox: vi.fn() },
       handlers: { issueRetry: vi.fn() },
     });
 

packages/engine/src/__tests__/reliability-interactions/auto-recovery-dispatch.test.ts

@@ -8,7 +8,7 @@ describe("reliability interaction: auto-recovery dispatcher precedence", () => {
   it("mode off preserves legacy pausedReason contract across wired classes", () => {
     const dispatcher = new AutoRecoveryDispatcher({
       taskStore: {} as never,
-      auditEmitter: { database: vi.fn(async () => {}), git: vi.fn(), filesystem: vi.fn() },
+      auditEmitter: { database: vi.fn(async () => {}), git: vi.fn(), filesystem: vi.fn(), sandbox: vi.fn() },
     });
 
     const wired = [

packages/engine/src/agent-tools.ts

@@ -1838,7 +1838,7 @@ export function createSendMessageTool(
   options?: { autoRecovery?: ProjectSettings["autoRecovery"]; runAudit?: RunAuditor; taskStore?: TaskStore; settings?: Settings },
 ): ToolDefinition {
   const deliveryHandler = new MessageDeliveryAutoRecoveryHandler({
-    runAudit: options?.runAudit ?? { database: async () => {}, git: async () => {}, filesystem: async () => {} },
+    runAudit: options?.runAudit ?? { database: async () => {}, git: async () => {}, filesystem: async () => {}, sandbox: async () => {} },
   });
 
   return {
@@ -2167,7 +2167,7 @@ export function createPostRoomMessageTool(
   options?: { autoRecovery?: ProjectSettings["autoRecovery"]; runAudit?: RunAuditor; taskStore?: TaskStore; settings?: Settings },
 ): ToolDefinition {
   const deliveryHandler = new MessageDeliveryAutoRecoveryHandler({
-    runAudit: options?.runAudit ?? { database: async () => {}, git: async () => {}, filesystem: async () => {} },
+    runAudit: options?.runAudit ?? { database: async () => {}, git: async () => {}, filesystem: async () => {}, sandbox: async () => {} },
   });
 
   return {

packages/engine/src/sandbox/__tests__/audit.test.ts

@@ -17,7 +17,7 @@ function makeBackend(runImpl?: (command: string, options: SandboxRunOptions) =>
       policy.onFallback?.({ fromBackendId: "sandbox-exec", toBackendId: "native", reason: "unavailable" });
     }),
     run: runImpl ?? vi.fn(async () => ({ stdout: "ok", stderr: "", exitCode: 0, signal: null, timedOut: false, bufferExceeded: false })),
-    runStreaming: vi.fn(async () => ({ outcome: "success", stdout: "", stderr: "", bufferOverflow: false })),
+    runStreaming: vi.fn(async () => ({ outcome: "success" as const, stdout: "", stderr: "", bufferOverflow: false })),
     dispose: vi.fn(async () => {}),
   };
 }
@@ -39,8 +39,9 @@ describe("withSandboxAudit", () => {
     await backend.prepare({ allowNetwork: false });
     await backend.prepare({ allowNetwork: false });
 
-    const prepareEvents = auditor.sandbox.mock.calls.filter(([input]) => input.type === "sandbox:prepare");
-    const fallbackEvents = auditor.sandbox.mock.calls.filter(([input]) => input.type === "sandbox:fallback");
+    const sandboxCalls = auditor.sandbox.mock.calls as unknown as Array<[Parameters<RunAuditor["sandbox"]>[0]]>;
+    const prepareEvents = sandboxCalls.filter(([input]) => input.type === "sandbox:prepare");
+    const fallbackEvents = sandboxCalls.filter(([input]) => input.type === "sandbox:fallback");
     expect(prepareEvents).toHaveLength(1);
     expect(fallbackEvents).toHaveLength(2);
   });