review(docs): #1735 patch API spec lines describing awareness_namespace

#1737 deletes the awareness_namespace column from `workspaces` and the provisioner env injection that backed it. Two API-spec lines still describe the field as if it were live, which would mislead any external integrator reading the docs against a post-#1737 backend: - docs/api-reference.md:106 listed `awareness_namespace` as a column on the `workspaces` row. - docs/api-protocol/platform-api.md:93 claimed workspace creation "assigns an awareness_namespace on the workspace row" and the namespace is "later injected into the provisioned runtime". Both are factually wrong post-#1737. Patched. The broader docs sweep (~30 more references across `docs/architecture/memory.md`, `docs/agent-runtime/*`, READMEs, superpowers plans, etc.) is tracked in #1753 as a docs-only follow-up — those are narrative / handbook copy, not contract. Refs: #1735 (RFC), #1737 (the backend removal PR this rebases on), #1753 (docs sweep follow-up), review-finding C3 (API doc contradiction). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
chore(workspace-server): #1735 remove unused Awareness namespace surface
2026-05-23 16:57:14 -07:00 · 2026-05-23 16:55:10 -07:00 · 2026-05-23 23:29:00 +00:00 · 2026-05-23 16:21:22 -07:00 · 2026-05-23 22:40:30 +00:00 · 2026-05-23 22:20:25 +00:00
23 changed files with 658 additions and 40 deletions
@@ -128,6 +128,7 @@ fi
 PR_AUTHOR=$(jq -r '.user.login // ""' "$PR_JSON")
 PR_HEAD_SHA=$(jq -r '.head.sha // ""' "$PR_JSON")
 PR_BASE_REF=$(jq -r '.base.ref // ""' "$PR_JSON")
+PR_BASE_SHA=$(jq -r '.base.sha // ""' "$PR_JSON")
 PR_STATE=$(jq -r '.state // ""' "$PR_JSON")
 DEFAULT_BRANCH="${DEFAULT_BRANCH:-main}"
 debug "pr_author=${PR_AUTHOR} pr_head=${PR_HEAD_SHA:0:7} pr_base=${PR_BASE_REF} pr_state=${PR_STATE}"
@@ -136,6 +137,10 @@ if [ "$PR_STATE" != "open" ]; then
  echo "::notice::PR ${PR_NUMBER} is ${PR_STATE} — exiting 0 (closed PRs do not gate)"
  exit 0
 fi
+if [ "$PR_HEAD_SHA" = "$PR_BASE_SHA" ]; then
+  echo "::notice::PR ${PR_NUMBER} has no diff (head == base) — exiting 0 (empty PRs do not gate)"
+  exit 0
+fi
 if [ "$PR_BASE_REF" != "$DEFAULT_BRANCH" ]; then
  echo "::notice::PR ${PR_NUMBER} targets ${PR_BASE_REF:-<unknown>} not ${DEFAULT_BRANCH} — ${TEAM}-review gate not applicable"
  exit 0
@@ -101,7 +101,8 @@ jobs:
    # AND-set: only the Mac arm64 runner advertises macos-self-hosted.
    # See "RUNNER TARGETING" header note for why bare self-hosted is unsafe.
    runs-on: [self-hosted, macos-self-hosted]
-    # ADVISORY: never blocks. See safety contract point 3.
+    # ADVISORY: never blocks. See safety contract point 3. mc#774
+    # internal#418 — tracked: arm64 advisory pilot, non-gating by design.
    continue-on-error: true
    # event_name gate: functional (only meaningful on push/PR) AND keeps
    # this job out of ci-required-drift.py:ci_job_names() so F1 can never
@@ -25,7 +25,7 @@ permissions:
 jobs:
  shellcheck-arm64:
    name: shellcheck-arm64 (pilot)
-    runs-on: [self-hosted, arm64]
+    runs-on: [self-hosted, arm64-darwin]
    # NOT a required check; safe to sit pending until Mac runner is up.
    # If the Mac runner has trouble pulling actions/checkout we fall
    # back to a plain git clone (see step 'fallback clone').
@@ -52,6 +52,7 @@ jobs:
          fetch-depth: 1

      - name: Install shellcheck (arm64)
+        continue-on-error: true
        run: |
          set -eu
          if command -v shellcheck >/dev/null 2>&1; then
@@ -71,11 +72,16 @@ jobs:
          shellcheck --version | head -2

      - name: Run shellcheck on .gitea/scripts/*.sh
+        continue-on-error: true
        run: |
          set -eu
          # Only the scripts we control under .gitea/scripts. Pilot
          # scope is intentionally narrow — broaden in a follow-up
          # once the lane is proven.
+          if ! command -v shellcheck >/dev/null 2>&1; then
+            echo "WARN: shellcheck binary not found — skipping (pilot mode)"
+            exit 0
+          fi
          mapfile -t TARGETS < <(find .gitea/scripts -maxdepth 2 -type f -name '*.sh' | sort)
          if [ "${#TARGETS[@]}" -eq 0 ]; then
            echo "No .sh files found under .gitea/scripts — nothing to check"
@@ -73,6 +73,17 @@ jobs:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

+      # Keep Docker auth/buildx state inside the job temp dir. Publish
+      # runners can inherit a HOME/DOCKER_CONFIG path that is host-owned
+      # and not writable from the job container; docker login otherwise
+      # fails before the image build starts.
+      - name: Prepare writable Docker config
+        run: |
+          set -euo pipefail
+          export DOCKER_CONFIG="$RUNNER_TEMP/docker-config"
+          mkdir -p "$DOCKER_CONFIG/buildx/certs"
+          echo "DOCKER_CONFIG=$DOCKER_CONFIG" >> "$GITHUB_ENV"
+
      - name: Log in to ECR
        env:
          IMAGE_NAME: ${{ env.IMAGE_NAME }}
@@ -234,6 +234,8 @@ jobs:
    name: Production auto-deploy
    needs: build-and-push
    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    # Side-effect deploy only; image publish success is the durable artifact. mc#774
+    continue-on-error: true
    # Publish/release lane (internal#462) — production deploy of a merged
    # fix; reserved capacity, never queued behind PR-CI.
    runs-on: publish
@@ -33,6 +33,8 @@ interface HermesProvider {
  models: string[];
 }

+const DEFAULT_CREATE_MODEL = "anthropic:claude-opus-4-7";
+
 // All providers supported by Hermes runtime via providers.resolve_provider().
 // `defaultModel` is the slug injected into the workspace provision request
 // when the user picks this provider — template-hermes's derive-provider.sh
@@ -68,6 +70,10 @@ export function CreateWorkspaceButton() {
  const [creating, setCreating] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const [workspaces, setWorkspaces] = useState<WorkspaceOption[]>([]);
+  const [displayEnabled, setDisplayEnabled] = useState(false);
+  const [displayInstanceType, setDisplayInstanceType] = useState("t3.xlarge");
+  const [displayRootGB, setDisplayRootGB] = useState("80");
+  const [displayResolution, setDisplayResolution] = useState("1920x1080");
  // Templates fetched from /api/templates — drives the dynamic provider
  // filter below. Same data source ConfigTab uses (PR #2454). When the
  // selected template declares `runtime_config.providers` in its
@@ -223,6 +229,10 @@ export function CreateWorkspaceButton() {
    setParentId("");
    setBudgetLimit("");
    setError(null);
+    setDisplayEnabled(false);
+    setDisplayInstanceType("t3.xlarge");
+    setDisplayRootGB("80");
+    setDisplayResolution("1920x1080");
    setHermesProvider("anthropic");
    setExternalRuntime("external");
    setHermesApiKey("");
@@ -264,6 +274,8 @@ export function CreateWorkspaceButton() {
      const parsedBudget = budgetLimit.trim()
        ? parseFloat(budgetLimit)
        : null;
+      const [displayWidth, displayHeight] = displayResolution.split("x").map((v) => parseInt(v, 10));
+      const parsedRootGB = parseInt(displayRootGB, 10);

      const createResp = await api.post<{
        id: string;
@@ -280,6 +292,21 @@ export function CreateWorkspaceButton() {
        tier,
        parent_id: parentId || undefined,
        budget_limit: parsedBudget,
+        ...(!isExternal && !isHermes ? { model: DEFAULT_CREATE_MODEL } : {}),
+        ...(displayEnabled
+          ? {
+              compute: {
+                instance_type: displayInstanceType,
+                volume: { root_gb: Number.isFinite(parsedRootGB) ? parsedRootGB : 80 },
+                display: {
+                  mode: "desktop-control",
+                  protocol: "novnc",
+                  width: Number.isFinite(displayWidth) ? displayWidth : 1920,
+                  height: Number.isFinite(displayHeight) ? displayHeight : 1080,
+                },
+              },
+            }
+          : {}),
        canvas: { x: Math.random() * 400 + 100, y: Math.random() * 300 + 100 },
        // Runtime=external flips the backend into awaiting-agent mode:
        // no container provisioning, token minted, connection payload
@@ -447,6 +474,73 @@ export function CreateWorkspaceButton() {
              </div>
            </div>

+            {!isExternal && (
+              <div className="rounded-lg border border-line/50 bg-surface-card/40 p-3">
+                <div className="mb-2 text-[11px] font-medium text-ink-mid">
+                  Container Config
+                </div>
+                <label className="flex items-center justify-between gap-3">
+                  <span className="text-xs font-medium text-ink">Display</span>
+                  <input
+                    type="checkbox"
+                    checked={displayEnabled}
+                    onChange={(e) => setDisplayEnabled(e.target.checked)}
+                    aria-label="Enable display"
+                    className="h-4 w-4"
+                  />
+                </label>
+                {displayEnabled && (
+                  <div className="mt-3 grid grid-cols-2 gap-2">
+                    <div>
+                      <label htmlFor="display-instance-type" className="mb-1 block text-[11px] text-ink-mid">
+                        Instance
+                      </label>
+                      <select
+                        id="display-instance-type"
+                        value={displayInstanceType}
+                        onChange={(e) => setDisplayInstanceType(e.target.value)}
+                        className="w-full bg-surface-card/60 border border-line/50 rounded-lg px-2 py-2 text-xs text-ink focus:outline-none focus:border-accent/60 focus:ring-1 focus:ring-accent/20 transition-colors"
+                      >
+                        <option value="t3.large">t3.large</option>
+                        <option value="t3.xlarge">t3.xlarge</option>
+                        <option value="m6i.xlarge">m6i.xlarge</option>
+                        <option value="c6i.xlarge">c6i.xlarge</option>
+                      </select>
+                    </div>
+                    <div>
+                      <label htmlFor="display-root-gb" className="mb-1 block text-[11px] text-ink-mid">
+                        Disk GB
+                      </label>
+                      <input
+                        id="display-root-gb"
+                        type="number"
+                        min="30"
+                        max="500"
+                        value={displayRootGB}
+                        onChange={(e) => setDisplayRootGB(e.target.value)}
+                        className="w-full bg-surface-card/60 border border-line/50 rounded-lg px-2 py-2 text-xs text-ink focus:outline-none focus:border-accent/60 focus:ring-1 focus:ring-accent/20 transition-colors"
+                      />
+                    </div>
+                    <div className="col-span-2">
+                      <label htmlFor="display-resolution" className="mb-1 block text-[11px] text-ink-mid">
+                        Resolution
+                      </label>
+                      <select
+                        id="display-resolution"
+                        value={displayResolution}
+                        onChange={(e) => setDisplayResolution(e.target.value)}
+                        className="w-full bg-surface-card/60 border border-line/50 rounded-lg px-2 py-2 text-xs text-ink focus:outline-none focus:border-accent/60 focus:ring-1 focus:ring-accent/20 transition-colors"
+                      >
+                        <option value="1920x1080">1920 x 1080</option>
+                        <option value="1600x900">1600 x 900</option>
+                        <option value="1280x720">1280 x 720</option>
+                      </select>
+                    </div>
+                  </div>
+                )}
+              </div>
+            )}
+
            <div>
              <label className="text-[11px] text-ink-mid block mb-1">
                Parent Workspace
@@ -123,6 +123,46 @@ describe("CreateWorkspaceDialog", () => {
    expect(body.parent_id).toBeUndefined();
  });

+  it("omits compute config by default", async () => {
+    await openDialog();
+    fireEvent.change(screen.getByPlaceholderText("e.g. SEO Agent"), {
+      target: { value: "Plain Agent" },
+    });
+
+    const createBtn = screen.getAllByRole("button").find((b) => b.textContent === "Create");
+    fireEvent.click(createBtn!);
+
+    await waitFor(() => expect(mockPost).toHaveBeenCalled());
+    const body = mockPost.mock.calls[0][1] as Record<string, unknown>;
+    expect(body.compute).toBeUndefined();
+    expect(body.model).toBe("anthropic:claude-opus-4-7");
+  });
+
+  it("sends display compute profile when desktop display is enabled", async () => {
+    await openDialog();
+    fireEvent.change(screen.getByPlaceholderText("e.g. SEO Agent"), {
+      target: { value: "Desktop Agent" },
+    });
+    fireEvent.click(screen.getByLabelText("Enable display"));
+
+    const createBtn = screen.getAllByRole("button").find((b) => b.textContent === "Create");
+    fireEvent.click(createBtn!);
+
+    await waitFor(() => expect(mockPost).toHaveBeenCalled());
+    const body = mockPost.mock.calls[0][1] as Record<string, unknown>;
+    expect(body.model).toBe("anthropic:claude-opus-4-7");
+    expect(body.compute).toEqual({
+      instance_type: "t3.xlarge",
+      volume: { root_gb: 80 },
+      display: {
+        mode: "desktop-control",
+        protocol: "novnc",
+        width: 1920,
+        height: 1080,
+      },
+    });
+  });
+
  it("renders gracefully when GET /workspaces fails", async () => {
    mockGet.mockRejectedValueOnce(new Error("Network error"));
    await openDialog();
@@ -11,6 +11,7 @@ interface DisplayStatus {
  protocol?: string;
  width?: number;
  height?: number;
+  viewer_url?: string;
 }

 interface DisplayControlStatus {
@@ -93,6 +94,31 @@ export function DisplayTab({ workspaceId }: Props) {
    }
  };

+  const releaseControl = async () => {
+    const generation = requestGeneration.current;
+    const controlPath = `/workspaces/${workspaceId}/display/control`;
+    setControlBusy(true);
+    setControlError(null);
+    try {
+      const next = await api.post<DisplayControlStatus>(`${controlPath}/release`, {});
+      if (requestGeneration.current !== generation) return;
+      setControl(next);
+    } catch (err) {
+      if (requestGeneration.current !== generation) return;
+      setControlError("Failed to release control");
+      try {
+        const latest = await api.get<DisplayControlStatus>(controlPath);
+        if (requestGeneration.current !== generation) return;
+        setControl(latest);
+      } catch {
+        if (requestGeneration.current !== generation) return;
+        setControl(null);
+      }
+    } finally {
+      if (requestGeneration.current === generation) setControlBusy(false);
+    }
+  };
+
  if (error) {
    return (
      <div className="p-5">
@@ -185,7 +211,97 @@ export function DisplayTab({ workspaceId }: Props) {
    );
  }

-  return null;
+  return (
+    <div className="flex h-full min-h-[360px] flex-col bg-surface-sunken/30">
+      <div className="flex items-center justify-between gap-3 border-b border-line/50 px-4 py-3">
+        <div className="min-w-0">
+          <h3 className="text-sm font-medium text-ink">Desktop</h3>
+          <p className="mt-0.5 font-mono text-[10px] text-ink-mid">
+            {status.mode || "desktop-control"} · {status.protocol || "display"}
+          </p>
+        </div>
+        <DisplayControlBar
+          control={control}
+          controlBusy={controlBusy}
+          controlError={controlError}
+          onAcquire={acquireControl}
+          onRelease={releaseControl}
+        />
+      </div>
+      {status.viewer_url ? (
+        <iframe
+          title="Workspace desktop"
+          src={status.viewer_url}
+          className="min-h-0 flex-1 border-0 bg-black"
+          allow="clipboard-read; clipboard-write; fullscreen; pointer-lock"
+          referrerPolicy="no-referrer"
+        />
+      ) : (
+        <div className="flex flex-1 items-center justify-center p-8 text-center">
+          <div>
+            <h3 className="mb-1.5 text-sm font-medium text-ink">Display session is not ready.</h3>
+            <p className="max-w-xs text-[11px] leading-relaxed text-ink-mid">
+              This workspace has display configuration, but the desktop session URL is not available yet.
+            </p>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function DisplayControlBar({
+  control,
+  controlBusy,
+  controlError,
+  onAcquire,
+  onRelease,
+}: {
+  control: DisplayControlStatus | null;
+  controlBusy: boolean;
+  controlError: string | null;
+  onAcquire: () => void;
+  onRelease: () => void;
+}) {
+  return (
+    <div className="flex min-w-0 items-center gap-3">
+      {control && (
+        <div className="min-w-0 text-right">
+          <p className="truncate text-[11px] font-medium text-ink">
+            {control.controller === "none"
+              ? "No active controller"
+              : `Controlled by ${displayControlActorLabel(control)}`}
+          </p>
+          {control.expires_at && (
+            <p className="mt-0.5 truncate font-mono text-[10px] text-ink-mid">
+              Until {new Date(control.expires_at).toLocaleTimeString()}
+            </p>
+          )}
+          {controlError && <p className="mt-0.5 text-[10px] text-red-200">{controlError}</p>}
+        </div>
+      )}
+      {control?.controller === "none" && (
+        <button
+          type="button"
+          onClick={onAcquire}
+          disabled={controlBusy}
+          className="h-8 shrink-0 rounded border border-line bg-surface px-3 text-[11px] font-medium text-ink hover:bg-surface-elevated disabled:cursor-not-allowed disabled:opacity-60"
+        >
+          Take control
+        </button>
+      )}
+      {control?.controller === "user" && control.controlled_by === "admin-token" && (
+        <button
+          type="button"
+          onClick={onRelease}
+          disabled={controlBusy}
+          className="h-8 shrink-0 rounded border border-line bg-surface px-3 text-[11px] font-medium text-ink hover:bg-surface-elevated disabled:cursor-not-allowed disabled:opacity-60"
+        >
+          Release
+        </button>
+      )}
+    </div>
+  );
 }

 function displayControlActorLabel(control: DisplayControlStatus): string {
@@ -71,6 +71,61 @@ describe("DisplayTab", () => {
    });
  });

+  it("renders the desktop stream when a display session is available", async () => {
+    mockGet
+      .mockResolvedValueOnce({
+        available: true,
+        mode: "desktop-control",
+        protocol: "dcv",
+        width: 1920,
+        height: 1080,
+        viewer_url: "https://display.example.test/session/ws-display",
+      })
+      .mockResolvedValueOnce({
+        controller: "none",
+      });
+
+    render(<DisplayTab workspaceId="ws-display" />);
+
+    await waitFor(() => {
+      expect(screen.getByTitle("Workspace desktop")).toBeTruthy();
+    });
+    const frame = screen.getByTitle("Workspace desktop") as HTMLIFrameElement;
+    expect(frame.src).toBe("https://display.example.test/session/ws-display");
+    expect(screen.getByRole("button", { name: "Take control" })).toBeTruthy();
+  });
+
+  it("releases user display control", async () => {
+    mockGet
+      .mockResolvedValueOnce({
+        available: true,
+        mode: "desktop-control",
+        protocol: "dcv",
+        viewer_url: "https://display.example.test/session/ws-display",
+      })
+      .mockResolvedValueOnce({
+        controller: "user",
+        controlled_by: "admin-token",
+        expires_at: "2026-05-23T08:48:27Z",
+      });
+    mockPost.mockResolvedValueOnce({
+      controller: "none",
+    });
+
+    render(<DisplayTab workspaceId="ws-display" />);
+
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: "Release" })).toBeTruthy();
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Release" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: "Take control" })).toBeTruthy();
+    });
+    expect(mockPost).toHaveBeenCalledWith("/workspaces/ws-display/display/control/release", {});
+  });
+
  it("renders active display control locks as observe-only", async () => {
    mockGet
      .mockResolvedValueOnce({
@@ -90,8 +90,6 @@ Poll `GET /workspaces/:id/delegations` to check results. Each entry includes `de

 This is the recommended way for agents to delegate work — it works for all runtimes (Claude Code, LangGraph, etc.) since it operates at the platform level.

-Workspace creation also assigns an `awareness_namespace` on the workspace row. That namespace is later injected into the provisioned runtime.
-
 ### Registry

 | Method | Path | Description | Auth |
@@ -103,7 +103,7 @@ Migration files live in `workspace-server/migrations/` (latest: `022_workspace_s

 | Table | Description |
 |-------|-------------|
-| `workspaces` | Core entity — status, runtime, `agent_card` JSONB, heartbeat columns, `current_task`, `awareness_namespace`, `workspace_dir` |
+| `workspaces` | Core entity — status, runtime, `agent_card` JSONB, heartbeat columns, `current_task`, `workspace_dir` |
 | `canvas_layouts` | Per-workspace x/y canvas position |
 | `structure_events` | Append-only event log (workspace lifecycle, agent, approval events) |
 | `activity_logs` | A2A communications, task updates, agent logs, errors. `error_detail` is populated by the scheduler so cron run history can surface failure reasons. |
@@ -111,12 +111,13 @@ const maxProxyResponseBody = 10 << 20
 //     a generic 502 page to canvas. 10s is well above realistic intra-region
 //     latencies and well below CF's edge timeout.
 //
-//  3. Transport.ResponseHeaderTimeout — 180s default. From request-body-end
+//  3. Transport.ResponseHeaderTimeout — 5min default. From request-body-end
 //     to response-headers-start. Configurable via
 //     A2A_PROXY_RESPONSE_HEADER_TIMEOUT (envx.Duration). Covers cold-start
 //     first-byte (30-60s OAuth flow above) with enough room for Opus agent
-//     turns (big context + internal delegate_task round-trips routinely exceed
-//     the old 60s ceiling). Body streaming after headers is governed by the
+//     turns and Codex scheduled tasks (big context + internal delegate_task
+//     round-trips routinely exceed the old 60s/180s ceilings). Body streaming
+//     after headers is governed by the
 //     per-request context deadline, NOT this timeout — so multi-minute agent
 //     responses still work fine.
 //
@@ -131,7 +132,7 @@ var a2aClient = &http.Client{
 			Timeout:   10 * time.Second,
 			KeepAlive: 30 * time.Second,
 		}).DialContext,
-		ResponseHeaderTimeout: envx.Duration("A2A_PROXY_RESPONSE_HEADER_TIMEOUT", 180*time.Second),
+		ResponseHeaderTimeout: envx.Duration("A2A_PROXY_RESPONSE_HEADER_TIMEOUT", 5*time.Minute),
 		TLSHandshakeTimeout:   10 * time.Second,
 		// MaxIdleConns / IdleConnTimeout: stdlib defaults are fine; agent
 		// fan-in is bounded by the platform's broadcaster fan-out, not by
@@ -28,8 +28,8 @@ type proxyDispatchBuildError struct{ err error }
 func (e *proxyDispatchBuildError) Error() string { return e.err.Error() }

 // handleA2ADispatchError translates a forward-call failure into a proxyA2AError,
-// runs the reactive container-health check, and (when `logActivity` is true)
-// schedules a detached LogActivity goroutine for the failed attempt.
+// runs the reactive container-health check, and records the outcome. Busy
+// targets that are successfully queued are logged as queued, not failed.
 func (h *WorkspaceHandler) handleA2ADispatchError(ctx context.Context, workspaceID, callerID string, body []byte, a2aMethod string, err error, durationMs int, logActivity bool) (int, []byte, *proxyA2AError) {
 	// Build-time failure (couldn't even create the http.Request) — return
 	// a 500 without the reactive-health / busy-retry paths.
@@ -45,10 +45,10 @@ func (h *WorkspaceHandler) handleA2ADispatchError(ctx context.Context, workspace

 	containerDead := h.maybeMarkContainerDead(ctx, workspaceID)

-	if logActivity {
-		h.logA2AFailure(ctx, workspaceID, callerID, body, a2aMethod, err, durationMs)
-	}
 	if containerDead {
+		if logActivity {
+			h.logA2AFailure(ctx, workspaceID, callerID, body, a2aMethod, err, durationMs)
+		}
 		return 0, nil, &proxyA2AError{
 			Status:   http.StatusServiceUnavailable,
 			Response: gin.H{"error": "workspace agent unreachable — container restart triggered", "restarting": true},
@@ -108,6 +108,9 @@ func (h *WorkspaceHandler) handleA2ADispatchError(ctx context.Context, workspace
 			ctx, workspaceID, callerID, PriorityTask, body, a2aMethod, idempotencyKey, expiresAt,
 		); qerr == nil {
 			log.Printf("ProxyA2A: target %s busy — enqueued as %s (depth=%d)", workspaceID, qid, depth)
+			if logActivity {
+				h.logA2ABusyQueued(ctx, workspaceID, callerID, body, a2aMethod, durationMs)
+			}
 			respBody, _ := json.Marshal(gin.H{
 				"queued":      true,
 				"queue_id":    qid,
@@ -121,6 +124,9 @@ func (h *WorkspaceHandler) handleA2ADispatchError(ctx context.Context, workspace
 			// make delegation silently disappear.
 			log.Printf("ProxyA2A: enqueue for %s failed (%v) — falling back to 503", workspaceID, qerr)
 		}
+		if logActivity {
+			h.logA2AFailure(ctx, workspaceID, callerID, body, a2aMethod, err, durationMs)
+		}
 		return 0, nil, &proxyA2AError{
 			Status:  http.StatusServiceUnavailable,
 			Headers: map[string]string{"Retry-After": strconv.Itoa(busyRetryAfterSeconds)},
@@ -131,6 +137,9 @@ func (h *WorkspaceHandler) handleA2ADispatchError(ctx context.Context, workspace
 			},
 		}
 	}
+	if logActivity {
+		h.logA2AFailure(ctx, workspaceID, callerID, body, a2aMethod, err, durationMs)
+	}
 	return 0, nil, &proxyA2AError{
 		Status:   http.StatusBadGateway,
 		Response: gin.H{"error": "failed to reach workspace agent"},
@@ -311,6 +320,33 @@ func (h *WorkspaceHandler) logA2AFailure(ctx context.Context, workspaceID, calle
 	})
 }

+// logA2ABusyQueued records that a push attempt reached a live but busy
+// workspace and was durably queued for heartbeat drain.
+func (h *WorkspaceHandler) logA2ABusyQueued(ctx context.Context, workspaceID, callerID string, body []byte, a2aMethod string, durationMs int) {
+	var wsName string
+	db.DB.QueryRowContext(ctx, `SELECT name FROM workspaces WHERE id = $1`, workspaceID).Scan(&wsName)
+	if wsName == "" {
+		wsName = workspaceID
+	}
+	summary := a2aMethod + " → " + wsName + " (queued: target busy)"
+	parent := ctx
+	h.goAsync(func() {
+		logCtx, cancel := context.WithTimeout(context.WithoutCancel(parent), 30*time.Second)
+		defer cancel()
+		LogActivity(logCtx, h.broadcaster, ActivityParams{
+			WorkspaceID:  workspaceID,
+			ActivityType: "a2a_receive",
+			SourceID:     nilIfEmpty(callerID),
+			TargetID:     &workspaceID,
+			Method:       &a2aMethod,
+			Summary:      &summary,
+			RequestBody:  json.RawMessage(body),
+			DurationMs:   &durationMs,
+			Status:       "ok",
+		})
+	})
+}
+
 // logA2ASuccess records a successful A2A round-trip and (for canvas-initiated
 // 2xx/3xx responses) broadcasts an A2A_RESPONSE event so the frontend can
 // receive the reply without polling.
@@ -1779,6 +1779,58 @@ func TestHandleA2ADispatchError_ContextDeadline(t *testing.T) {
 	}
 }

+func TestHandleA2ADispatchError_BusyEnqueueLogsQueuedNotFailure(t *testing.T) {
+	mock := setupTestDB(t)
+	setupTestRedis(t)
+	handler := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, handler)
+
+	mock.ExpectQuery(`INSERT INTO a2a_queue`).
+		WithArgs("ws-busy", nil, PriorityTask, "{}", "message/send", nil, nil).
+		WillReturnRows(sqlmock.NewRows([]string{"id"}).AddRow("11111111-1111-1111-1111-111111111111"))
+	mock.ExpectQuery(`SELECT COUNT\(\*\) FROM a2a_queue`).
+		WithArgs("ws-busy").
+		WillReturnRows(sqlmock.NewRows([]string{"count"}).AddRow(1))
+	mock.ExpectQuery(`SELECT name FROM workspaces WHERE id =`).
+		WithArgs("ws-busy").
+		WillReturnRows(sqlmock.NewRows([]string{"name"}).AddRow("Busy Target"))
+	mock.ExpectExec("INSERT INTO activity_logs").
+		WithArgs(
+			"ws-busy",
+			"a2a_receive",
+			nil,
+			sqlmock.AnyArg(),
+			sqlmock.AnyArg(),
+			sqlmock.AnyArg(),
+			sqlmock.AnyArg(),
+			nil,
+			nil,
+			sqlmock.AnyArg(),
+			"ok",
+			nil,
+		).
+		WillReturnResult(sqlmock.NewResult(0, 1))
+
+	status, body, perr := handler.handleA2ADispatchError(
+		context.Background(), "ws-busy", "", []byte("{}"), "message/send",
+		context.DeadlineExceeded, 180002, true,
+	)
+	if perr != nil {
+		t.Fatalf("expected busy enqueue success, got proxy error: %+v", perr)
+	}
+	if status != http.StatusAccepted {
+		t.Fatalf("got status %d, want 202", status)
+	}
+	if !bytes.Contains(body, []byte(`"queued":true`)) {
+		t.Fatalf("expected queued response body, got %s", string(body))
+	}
+
+	time.Sleep(80 * time.Millisecond)
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatalf("unmet expectations; busy enqueue must log status=ok, not error: %v", err)
+	}
+}
+
 func TestHandleA2ADispatchError_BuildError(t *testing.T) {
 	setupTestDB(t)
 	setupTestRedis(t)
@@ -2354,7 +2406,7 @@ func TestLookupDeliveryMode_ContextCanceled_FailsClosed(t *testing.T) {
 // ==================== a2aClient ResponseHeaderTimeout config ====================

 func TestA2AClientResponseHeaderTimeout(t *testing.T) {
-	const defaultTimeout = 180 * time.Second
+	const defaultTimeout = 5 * time.Minute

 	// Default (unset env) — a2aClient was initialised at package load time.
 	if a2aClient.Transport.(*http.Transport).ResponseHeaderTimeout != defaultTimeout {
@@ -2378,7 +2430,7 @@ func TestA2AClientResponseHeaderTimeout(t *testing.T) {
 	t.Run("invalid A2A_PROXY_RESPONSE_HEADER_TIMEOUT falls back to default", func(t *testing.T) {
 		t.Setenv("A2A_PROXY_RESPONSE_HEADER_TIMEOUT", "not-a-duration")
 		// Simulate what envx.Duration does with an invalid value.
-		var fallback = 180 * time.Second
+		var fallback = 5 * time.Minute
 		override := fallback
 		if v := os.Getenv("A2A_PROXY_RESPONSE_HEADER_TIMEOUT"); v != "" {
 			if d, err := time.ParseDuration(v); err == nil && d > 0 {
@@ -159,7 +159,8 @@ func generateAppInstallationToken() (string, time.Time, error) {
 	req, _ := http.NewRequest("POST", fmt.Sprintf("https://api.github.com/app/installations/%d/access_tokens", installID), nil)
 	req.Header.Set("Authorization", "Bearer "+signed)
 	req.Header.Set("Accept", "application/vnd.github+json")
-	resp, err := http.DefaultClient.Do(req)
+	client := &http.Client{Timeout: 30 * time.Second}
+	resp, err := client.Do(req)
 	if err != nil {
 		return "", time.Time{}, err
 	}
@@ -54,6 +54,11 @@ func (h *MemoryHandler) List(c *gin.Context) {
 		entry.Value = json.RawMessage(value)
 		entries = append(entries, entry)
 	}
+	if err := rows.Err(); err != nil {
+		log.Printf("Memory list iteration error: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "query iteration failed"})
+		return
+	}

 	c.JSON(http.StatusOK, entries)
 }
@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"database/sql"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"testing"
@@ -74,6 +75,34 @@ func TestMemoryList_DBError(t *testing.T) {
 	}
 }

+// TestMemoryList_RowsErr_Returns500 verifies that a rows.Err() set during
+// iteration causes the handler to return 500 rather than partial results.
+func TestMemoryList_RowsErr_Returns500(t *testing.T) {
+	mock := setupTestDB(t)
+	setupTestRedis(t)
+	handler := NewMemoryHandler()
+
+	cols := []string{"key", "value", "version", "expires_at", "updated_at"}
+	mock.ExpectQuery("SELECT key, value, version, expires_at, updated_at").
+		WithArgs("ws-rowerr").
+		WillReturnRows(sqlmock.NewRows(cols).
+			AddRow("ok-key", []byte(`"val"`), int64(1), nil, time.Now()).
+			RowError(0, errors.New("storage engine fault")))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: "ws-rowerr"}}
+	c.Request = httptest.NewRequest("GET", "/workspaces/ws-rowerr/memory", nil)
+	handler.List(c)
+
+	if w.Code != http.StatusInternalServerError {
+		t.Errorf("rows.Err() must yield 500, got %d: %s", w.Code, w.Body.String())
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet sqlmock expectations: %v", err)
+	}
+}
+
 // ==================== GET /workspaces/:id/memory/:key (Get) ====================

 func TestMemoryGet_Success(t *testing.T) {
@@ -6,6 +6,9 @@ import (
 	"encoding/json"
 	"fmt"
 	"log"
+	"net/url"
+	"os"
+	"strings"

 	"github.com/Molecule-AI/molecule-monorepo/platform/internal/db"
 	"github.com/Molecule-AI/molecule-monorepo/platform/internal/models"
@@ -15,6 +18,10 @@ import (
 const (
 	workspaceComputeDiskFloorGB   = 30
 	workspaceComputeDiskCeilingGB = 500
+	workspaceDisplayMinWidth      = 800
+	workspaceDisplayMaxWidth      = 3840
+	workspaceDisplayMinHeight     = 600
+	workspaceDisplayMaxHeight     = 2160
 )

 type workspaceDisplayResponse struct {
@@ -25,6 +32,7 @@ type workspaceDisplayResponse struct {
 	Width     int    `json:"width,omitempty"`
 	Height    int    `json:"height,omitempty"`
 	Status    string `json:"status,omitempty"`
+	ViewerURL string `json:"viewer_url,omitempty"`
 }

 var workspaceComputeInstanceAllowlist = map[string]struct{}{
@@ -54,12 +62,12 @@ func validateWorkspaceCompute(compute models.WorkspaceCompute) error {
 		return fmt.Errorf("unsupported compute.display.mode")
 	}
 	switch compute.Display.Protocol {
-	case "", "dcv":
+	case "", "dcv", "novnc":
 	default:
 		return fmt.Errorf("unsupported compute.display.protocol")
 	}
-	if compute.Display.Width < 0 || compute.Display.Height < 0 {
-		return fmt.Errorf("compute.display width/height must be non-negative")
+	if err := validateWorkspaceDisplayDimensions(compute.Display.Width, compute.Display.Height); err != nil {
+		return err
 	}
 	return nil
 }
@@ -71,13 +79,26 @@ func validateWorkspaceDisplayConfig(display models.WorkspaceComputeDisplay) erro
 		return fmt.Errorf("unsupported compute.display.mode")
 	}
 	switch display.Protocol {
-	case "", "dcv":
+	case "", "dcv", "novnc":
 	default:
 		return fmt.Errorf("unsupported compute.display.protocol")
 	}
-	if display.Width < 0 || display.Height < 0 {
+	if err := validateWorkspaceDisplayDimensions(display.Width, display.Height); err != nil {
+		return err
+	}
+	return nil
+}
+
+func validateWorkspaceDisplayDimensions(width, height int) error {
+	if width < 0 || height < 0 {
 		return fmt.Errorf("compute.display width/height must be non-negative")
 	}
+	if width != 0 && (width < workspaceDisplayMinWidth || width > workspaceDisplayMaxWidth) {
+		return fmt.Errorf("compute.display.width must be between %d and %d", workspaceDisplayMinWidth, workspaceDisplayMaxWidth)
+	}
+	if height != 0 && (height < workspaceDisplayMinHeight || height > workspaceDisplayMaxHeight) {
+		return fmt.Errorf("compute.display.height must be between %d and %d", workspaceDisplayMinHeight, workspaceDisplayMaxHeight)
+	}
 	return nil
 }

@@ -196,6 +217,18 @@ func (h *WorkspaceHandler) Display(c *gin.Context) {
 		})
 		return
 	}
+	if viewerURL := workspaceDisplayViewerURL(workspaceID); viewerURL != "" {
+		c.JSON(200, workspaceDisplayResponse{
+			Available: true,
+			Mode:      compute.Display.Mode,
+			Protocol:  compute.Display.Protocol,
+			Width:     compute.Display.Width,
+			Height:    compute.Display.Height,
+			Status:    "ready",
+			ViewerURL: viewerURL,
+		})
+		return
+	}
 	c.JSON(200, workspaceDisplayResponse{
 		Available: false,
 		Reason:    "display_session_unavailable",
@@ -206,3 +239,15 @@ func (h *WorkspaceHandler) Display(c *gin.Context) {
 		Status:    "not_configured",
 	})
 }
+
+func workspaceDisplayViewerURL(workspaceID string) string {
+	base := strings.TrimRight(os.Getenv("DISPLAY_VIEWER_BASE_URL"), "/")
+	if base == "" {
+		return ""
+	}
+	parsed, err := url.Parse(base)
+	if err != nil || parsed.Scheme != "https" || parsed.Host == "" {
+		return ""
+	}
+	return base + "/" + url.PathEscape(workspaceID)
+}
@@ -43,6 +43,20 @@ func TestValidateWorkspaceCompute_RejectsOutOfRangeRootVolume(t *testing.T) {
 	}
 }

+func TestValidateWorkspaceCompute_RejectsOutOfRangeDisplayDimensions(t *testing.T) {
+	for _, display := range []models.WorkspaceComputeDisplay{
+		{Mode: "desktop-control", Protocol: "novnc", Width: 799, Height: 1080},
+		{Mode: "desktop-control", Protocol: "novnc", Width: 3841, Height: 1080},
+		{Mode: "desktop-control", Protocol: "novnc", Width: 1920, Height: 599},
+		{Mode: "desktop-control", Protocol: "novnc", Width: 1920, Height: 2161},
+	} {
+		compute := models.WorkspaceCompute{Display: display}
+		if err := validateWorkspaceCompute(compute); err == nil {
+			t.Fatalf("validateWorkspaceCompute accepted display size %dx%d", display.Width, display.Height)
+		}
+	}
+}
+
 func TestWorkspaceComputeJSON_OmitsEmptyNestedSections(t *testing.T) {
 	got, err := workspaceComputeJSON(models.WorkspaceCompute{
 		InstanceType: "m6i.xlarge",
@@ -141,6 +155,7 @@ func TestBuildProvisionerConfig_CopiesComputeSizingFromPayload(t *testing.T) {
 			Compute: models.WorkspaceCompute{
 				InstanceType: "m6i.xlarge",
 				Volume:       models.WorkspaceComputeVolume{RootGB: 100},
+				Display:      models.WorkspaceComputeDisplay{Mode: "desktop-control", Protocol: "novnc", Width: 1920, Height: 1080},
 			},
 		},
 		nil,
@@ -153,6 +168,12 @@ func TestBuildProvisionerConfig_CopiesComputeSizingFromPayload(t *testing.T) {
 	if cfg.DiskGB != 100 {
 		t.Errorf("cfg.DiskGB = %d, want 100", cfg.DiskGB)
 	}
+	if cfg.Display.Mode != "desktop-control" || cfg.Display.Protocol != "novnc" {
+		t.Errorf("cfg.Display mode/protocol = %q/%q, want desktop-control/novnc", cfg.Display.Mode, cfg.Display.Protocol)
+	}
+	if cfg.Display.Width != 1920 || cfg.Display.Height != 1080 {
+		t.Errorf("cfg.Display size = %dx%d, want 1920x1080", cfg.Display.Width, cfg.Display.Height)
+	}
 }

 func TestWithStoredCompute_LoadsComputeForRestartPayloads(t *testing.T) {
@@ -216,7 +237,7 @@ func TestWorkspaceDisplay_DisplayConfiguredReturnsSessionUnavailableContract(t *

 	mock.ExpectQuery(`SELECT COALESCE\(compute, '\{\}'::jsonb\) FROM workspaces WHERE id = \$1`).
 		WithArgs("ws-display").
-		WillReturnRows(sqlmock.NewRows([]string{"compute"}).AddRow(`{"display":{"mode":"desktop-control","protocol":"dcv","width":1920,"height":1080}}`))
+		WillReturnRows(sqlmock.NewRows([]string{"compute"}).AddRow(`{"display":{"mode":"desktop-control","protocol":"novnc","width":1920,"height":1080}}`))

 	w := httptest.NewRecorder()
 	c, _ := gin.CreateTestContext(w)
@@ -241,8 +262,8 @@ func TestWorkspaceDisplay_DisplayConfiguredReturnsSessionUnavailableContract(t *
 	if resp["status"] != "not_configured" {
 		t.Fatalf("status = %v, want not_configured", resp["status"])
 	}
-	if resp["mode"] != "desktop-control" || resp["protocol"] != "dcv" {
-		t.Fatalf("mode/protocol = %v/%v, want desktop-control/dcv", resp["mode"], resp["protocol"])
+	if resp["mode"] != "desktop-control" || resp["protocol"] != "novnc" {
+		t.Fatalf("mode/protocol = %v/%v, want desktop-control/novnc", resp["mode"], resp["protocol"])
 	}
 	if resp["width"] != float64(1920) || resp["height"] != float64(1080) {
 		t.Fatalf("width/height = %v/%v, want 1920/1080", resp["width"], resp["height"])
@@ -255,6 +276,83 @@ func TestWorkspaceDisplay_DisplayConfiguredReturnsSessionUnavailableContract(t *
 	}
 }

+func TestWorkspaceDisplay_DisplayConfiguredWithViewerBaseReturnsAvailableSession(t *testing.T) {
+	mock := setupTestDB(t)
+	setupTestRedis(t)
+	t.Setenv("DISPLAY_VIEWER_BASE_URL", "https://display.example.test/sessions")
+	handler := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
+
+	mock.ExpectQuery(`SELECT COALESCE\(compute, '\{\}'::jsonb\) FROM workspaces WHERE id = \$1`).
+		WithArgs("ws-display").
+		WillReturnRows(sqlmock.NewRows([]string{"compute"}).AddRow(`{"display":{"mode":"desktop-control","protocol":"novnc","width":1920,"height":1080}}`))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: "ws-display"}}
+	c.Request = httptest.NewRequest("GET", "/workspaces/ws-display/display", nil)
+
+	handler.Display(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d: %s", w.Code, w.Body.String())
+	}
+	var resp map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse display response: %v", err)
+	}
+	if resp["available"] != true {
+		t.Fatalf("available = %v, want true", resp["available"])
+	}
+	if resp["viewer_url"] != "https://display.example.test/sessions/ws-display" {
+		t.Fatalf("viewer_url = %v, want workspace viewer URL", resp["viewer_url"])
+	}
+	if resp["reason"] != nil {
+		t.Fatalf("reason = %v, want omitted", resp["reason"])
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet sqlmock expectations: %v", err)
+	}
+}
+
+func TestWorkspaceDisplay_DisplayConfiguredWithInvalidViewerBaseReturnsUnavailable(t *testing.T) {
+	mock := setupTestDB(t)
+	setupTestRedis(t)
+	t.Setenv("DISPLAY_VIEWER_BASE_URL", "http://display.example.test/sessions")
+	handler := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
+
+	workspaceID := "ws-display"
+	mock.ExpectQuery(`SELECT COALESCE\(compute, '\{\}'::jsonb\) FROM workspaces WHERE id = \$1`).
+		WithArgs(workspaceID).
+		WillReturnRows(sqlmock.NewRows([]string{"compute"}).AddRow(`{"display":{"mode":"desktop-control","protocol":"novnc","width":1920,"height":1080}}`))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: workspaceID}}
+	c.Request = httptest.NewRequest("GET", "/workspaces/"+workspaceID+"/display", nil)
+
+	handler.Display(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d: %s", w.Code, w.Body.String())
+	}
+	var resp map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse display response: %v", err)
+	}
+	if resp["available"] != false {
+		t.Fatalf("available = %v, want false", resp["available"])
+	}
+	if resp["viewer_url"] != nil {
+		t.Fatalf("viewer_url = %v, want omitted for invalid viewer base", resp["viewer_url"])
+	}
+	if resp["reason"] != "display_session_unavailable" {
+		t.Fatalf("reason = %v, want display_session_unavailable", resp["reason"])
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet sqlmock expectations: %v", err)
+	}
+}
+
 func TestWorkspaceDisplay_IgnoresUnrelatedStoredComputeSizingDrift(t *testing.T) {
 	mock := setupTestDB(t)
 	setupTestRedis(t)
@@ -262,7 +360,7 @@ func TestWorkspaceDisplay_IgnoresUnrelatedStoredComputeSizingDrift(t *testing.T)

 	mock.ExpectQuery(`SELECT COALESCE\(compute, '\{\}'::jsonb\) FROM workspaces WHERE id = \$1`).
 		WithArgs("ws-display-sizing-drift").
-		WillReturnRows(sqlmock.NewRows([]string{"compute"}).AddRow(`{"instance_type":"old.large","display":{"mode":"desktop-control","protocol":"dcv","width":1920,"height":1080}}`))
+		WillReturnRows(sqlmock.NewRows([]string{"compute"}).AddRow(`{"instance_type":"old.large","display":{"mode":"desktop-control","protocol":"novnc","width":1920,"height":1080}}`))

 	w := httptest.NewRecorder()
 	c, _ := gin.CreateTestContext(w)
@@ -293,8 +293,14 @@ func (h *WorkspaceHandler) buildProvisionerConfig(
 		Runtime:         payload.Runtime,
 		InstanceType:    payload.Compute.InstanceType,
 		DiskGB:          int32(payload.Compute.Volume.RootGB),
-		EnvVars:         envVars,
-		PlatformURL:     h.platformURL,
+		Display: provisioner.WorkspaceDisplayConfig{
+			Mode:     payload.Compute.Display.Mode,
+			Width:    payload.Compute.Display.Width,
+			Height:   payload.Compute.Display.Height,
+			Protocol: payload.Compute.Display.Protocol,
+		},
+		EnvVars:     envVars,
+		PlatformURL: h.platformURL,
 		// Image left empty — molecule-core's runtime_image_pins table (mig
 		// 047, dead reader removed by RFC internal#617 / task #335) was an
 		// aspirational SSOT that never received a writer. CP's
@@ -152,14 +152,15 @@ func (p *CPProvisioner) adminAuthHeaders(req *http.Request) {
 }

 type cpProvisionRequest struct {
-	OrgID        string            `json:"org_id"`
-	WorkspaceID  string            `json:"workspace_id"`
-	Runtime      string            `json:"runtime"`
-	Tier         int               `json:"tier"`
-	InstanceType string            `json:"instance_type,omitempty"`
-	DiskGB       int32             `json:"disk_gb,omitempty"`
-	PlatformURL  string            `json:"platform_url"`
-	Env          map[string]string `json:"env"`
+	OrgID        string                 `json:"org_id"`
+	WorkspaceID  string                 `json:"workspace_id"`
+	Runtime      string                 `json:"runtime"`
+	Tier         int                    `json:"tier"`
+	InstanceType string                 `json:"instance_type,omitempty"`
+	DiskGB       int32                  `json:"disk_gb,omitempty"`
+	Display      WorkspaceDisplayConfig `json:"display,omitempty"`
+	PlatformURL  string                 `json:"platform_url"`
+	Env          map[string]string      `json:"env"`
 	// ConfigFiles are template + generated config files to write into the
 	// EC2 instance's /configs directory. OFFSEC-010: collected by
 	// collectCPConfigFiles which rejects symlinks and non-regular files
@@ -214,6 +215,7 @@ func (p *CPProvisioner) Start(ctx context.Context, cfg WorkspaceConfig) (string,
 		Tier:         cfg.Tier,
 		InstanceType: cfg.InstanceType,
 		DiskGB:       cfg.DiskGB,
+		Display:      cfg.Display,
 		PlatformURL:  cfg.PlatformURL,
 		Env:          env,
 		ConfigFiles:  configFiles,
@@ -197,6 +197,12 @@ func TestStart_HappyPath(t *testing.T) {
 		if body.DiskGB != 100 {
 			t.Errorf("disk_gb = %d, want 100", body.DiskGB)
 		}
+		if body.Display.Mode != "desktop-control" || body.Display.Protocol != "novnc" {
+			t.Errorf("display mode/protocol = %q/%q, want desktop-control/novnc", body.Display.Mode, body.Display.Protocol)
+		}
+		if body.Display.Width != 1920 || body.Display.Height != 1080 {
+			t.Errorf("display size = %dx%d, want 1920x1080", body.Display.Width, body.Display.Height)
+		}
 		w.WriteHeader(http.StatusCreated)
 		_, _ = io.WriteString(w, `{"instance_id":"i-abc123","state":"pending"}`)
 	}))
@@ -212,6 +218,7 @@ func TestStart_HappyPath(t *testing.T) {
 	id, err := p.Start(context.Background(), WorkspaceConfig{
 		WorkspaceID: "ws-1", Runtime: "python", Tier: 1, PlatformURL: "http://tenant",
 		InstanceType: "m6i.xlarge", DiskGB: 100,
+		Display: WorkspaceDisplayConfig{Mode: "desktop-control", Protocol: "novnc", Width: 1920, Height: 1080},
 	})
 	if err != nil {
 		t.Fatalf("Start: %v", err)
@@ -97,9 +97,10 @@ type WorkspaceConfig struct {
 	PluginsPath        string            // Host path to plugins directory (mounted at /plugins)
 	WorkspacePath      string            // Host path to bind-mount as /workspace (if empty, uses Docker named volume)
 	Tier               int
-	Runtime            string            // "langgraph" (default) or "claude-code", "codex", "ollama", "custom"
-	InstanceType       string            // Optional CP EC2 instance type override (SaaS only)
-	DiskGB             int32             // Optional CP root volume size override in GiB (SaaS only)
+	Runtime            string // "langgraph" (default) or "claude-code", "codex", "ollama", "custom"
+	InstanceType       string // Optional CP EC2 instance type override (SaaS only)
+	DiskGB             int32  // Optional CP root volume size override in GiB (SaaS only)
+	Display            WorkspaceDisplayConfig
 	EnvVars            map[string]string // Additional env vars (API keys, etc.)
 	PlatformURL        string
 	WorkspaceAccess    string // #65: "none" (default), "read_only", or "read_write"
@@ -120,6 +121,13 @@ type WorkspaceConfig struct {
 	Image string
 }

+type WorkspaceDisplayConfig struct {
+	Mode     string `json:"mode,omitempty"`
+	Width    int    `json:"width,omitempty"`
+	Height   int    `json:"height,omitempty"`
+	Protocol string `json:"protocol,omitempty"`
+}
+
 // selectImage resolves the final Docker image ref for a workspace. The handler
 // layer is the source of truth — if it set cfg.Image (the digest-pinned form
 // supplied by CP, the SSOT for runtime image pins; molecule-core's own