Merge branch 'main' into fix/canvas-keyboard-shortcuts-dialog-guard

.gitea/workflows/gate-check-v3.yml

@@ -32,6 +32,14 @@ on:
   # iterating all open PRs when PR_NUMBER is empty.
   workflow_dispatch:
 
+permissions:
+  # read: contents — for checkout (base ref, not PR head for security)
+  # read: pull-requests — for reading PR info via API
+  # write: pull-requests — for posting/updating gate-check comments
+  #   Without this the token cannot POST/PATCH /issues/comments → 403.
+  contents: read
+  pull-requests: write
+
 env:
   GITHUB_SERVER_URL: https://git.moleculesai.app
 

.gitea/workflows/publish-workspace-server-image.yml

@@ -20,6 +20,12 @@ name: publish-workspace-server-image
 #
 # ECR target: 153263036946.dkr.ecr.us-east-2.amazonaws.com/molecule-ai/*
 # Required secrets: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AUTO_SYNC_TOKEN
+#
+# mc#711: Docker daemon not accessible on ubuntu-latest runner (molecule-canonical-1
+# shows client-only in `docker info` — daemon not running). DinD mount is present but
+# daemon doesn't respond. Fix: add diagnostic step showing socket info so ops can
+# identify which runners have a live daemon. If no daemon is available, the job
+# fails fast with actionable output rather than silent deep failure.
 
 on:
   push:
@@ -52,36 +58,25 @@ env:
 
 jobs:
   build-and-push:
-    # REVERTED (infra/revert-docker-runner-label): `runs-on: ubuntu-latest` restored.
-    # The `docker` label is not registered on any act_runner. `runs-on: [ubuntu-latest, docker]`
-    # causes jobs to queue indefinitely with zero eligible runners — strictly worse than the
-    # pre-#599 coin-flip (50% success rate). Once the `docker` label is registered on
-    # ≥2 runners, re-apply the fix from #599 (infra/docker-runner-label).
-    # See issue #576 + infra-lead pulse ~00:30Z.
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      # Health check: verify Docker daemon is accessible before attempting any
-      # build steps. This fails loudly at step 1 when the runner's docker.sock
-      # is inaccessible (e.g. permission change, daemon restart, or group-membership
-      # drift) rather than silently continuing to step 2 where `docker build`
-      # fails deep in the process with a cryptic ECR auth error that doesn't
-      # surface the root cause.  Also reports the daemon version so operator
-      # can correlate with runner host logs.
-      - name: Verify Docker daemon access
+      - name: Diagnose Docker daemon access
         run: |
           set -euo pipefail
-          echo "::group::Docker daemon health check"
+          echo "::group::Docker daemon diagnosis"
           echo "Runner: ${HOSTNAME:-unknown}"
-          docker info 2>&1 | head -5 || {
-            echo "::error::Docker daemon is not accessible at /var/run/docker.sock"
-            echo "::error::Runner: ${HOSTNAME:-unknown}"
-            echo "::error::Check: (1) daemon is running, (2) runner user is in docker group, (3) sock permissions are 660+"
-            exit 1
-          }
-          echo "Docker daemon OK"
+          echo "--- Socket info ---"
+          ls -la /var/run/docker.sock 2>/dev/null || echo "/var/run/docker.sock: not found"
+          stat /var/run/docker.sock 2>/dev/null || true
+          echo "--- User info ---"
+          id
+          echo "--- docker version ---"
+          docker version 2>&1 || true
+          echo "--- docker info (full) ---"
+          docker info 2>&1 || echo "docker info failed: exit $?"
           echo "::endgroup::"
 
       # Pre-clone manifest deps before docker build.
@@ -100,9 +95,6 @@ jobs:
           MOLECULE_GITEA_TOKEN: ${{ secrets.AUTO_SYNC_TOKEN }}
         run: |
           set -euo pipefail
-          # clone-manifest.sh supports anonymous cloning for public repos (post-
-          # 2026-05-08 migration). The token is only needed for private repos.
-          # Do NOT require it — a missing secret would fail the build unnecessarily.
           mkdir -p .tenant-bundle-deps
           # Strip JSON5 comments before jq parsing — Integration Tester appends
           # `// Triggered by ...` which breaks `jq` in clone-manifest.sh.

canvas/src/components/mobile/__tests__/MobileCanvas.test.tsx

@@ -0,0 +1,185 @@
+// @vitest-environment jsdom
+/**
+ * MobileCanvas — mobile mini-graph with pinch-zoom and tap-to-open.
+ *
+ * Per WCAG 2.1 AA / mobile interaction:
+ *   - Reset button visible only after zoom/pan (zoomed state)
+ *   - Spawn FAB always visible with aria-label
+ *   - Legend always visible with all 5 status types
+ *   - WorkspacePill shows node count
+ *   - Node buttons clickable with onOpen(id) callback
+ *
+ * NOTE: No @testing-library/jest-dom — use DOM APIs.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render } from "@testing-library/react";
+import React from "react";
+
+import { MobileCanvas } from "../MobileCanvas";
+
+// ─── Mock dependencies ──────────────────────────────────────────────────────────
+
+vi.mock("@/lib/theme-provider", () => ({
+  useTheme: () => ({ theme: "dark", resolvedTheme: "dark", setTheme: vi.fn() }),
+}));
+
+const mockNodes = [
+  {
+    id: "ws-1",
+    position: { x: 100, y: 200 },
+    data: {
+      name: "Alpha Agent",
+      status: "online",
+      tier: 2,
+      parentId: null,
+      runtime: "langgraph",
+      activeTasks: 0,
+      role: "researcher",
+    },
+  },
+  {
+    id: "ws-2",
+    position: { x: 300, y: 400 },
+    data: {
+      name: "Beta Agent",
+      status: "degraded",
+      tier: 3,
+      parentId: "ws-1",
+      runtime: "claude-code",
+      activeTasks: 1,
+      role: "developer",
+    },
+  },
+  {
+    id: "ws-3",
+    position: { x: 0, y: 0 },
+    data: {
+      name: "Gamma Agent",
+      status: "offline",
+      tier: 1,
+      parentId: null,
+      runtime: "hermes",
+      activeTasks: 0,
+      role: "analyst",
+    },
+  },
+];
+
+vi.mock("@/store/canvas", () => ({
+  useCanvasStore: vi.fn((selector) => {
+    if (typeof selector === "function") {
+      return selector({ nodes: mockNodes });
+    }
+    return mockNodes;
+  }),
+  summarizeWorkspaceCapabilities: vi.fn((data: { status?: string; role?: string }) => ({
+    runtime: data.status ? "langgraph" : "unknown",
+    skillCount: 0,
+    currentTask: data.role ?? "",
+  })),
+}));
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+// ─── Render ────────────────────────────────────────────────────────────────────
+
+describe("MobileCanvas — render", () => {
+  it("renders the canvas container", () => {
+    render(
+      <MobileCanvas dark={true} onOpen={vi.fn()} onSpawn={vi.fn()} />,
+    );
+    const container = document.querySelector('[style*="position: absolute"]');
+    expect(container).toBeTruthy();
+  });
+
+  it("renders the legend with all 5 status types", () => {
+    render(
+      <MobileCanvas dark={true} onOpen={vi.fn()} onSpawn={vi.fn()} />,
+    );
+    const legend = Array.from(document.querySelectorAll("div")).find(
+      (d) => d.textContent?.includes("Legend"),
+    );
+    expect(legend).toBeTruthy();
+    expect(legend?.textContent).toContain("online");
+    expect(legend?.textContent).toContain("starting");
+    expect(legend?.textContent).toContain("degraded");
+    expect(legend?.textContent).toContain("failed");
+    expect(legend?.textContent).toContain("paused");
+  });
+
+  it("renders spawn FAB with correct aria-label", () => {
+    render(
+      <MobileCanvas dark={true} onOpen={vi.fn()} onSpawn={vi.fn()} />,
+    );
+    const fab = document.querySelector('button[aria-label="Spawn new agent"]');
+    expect(fab).toBeTruthy();
+  });
+
+  it("renders node buttons for each store node", () => {
+    render(
+      <MobileCanvas dark={true} onOpen={vi.fn()} onSpawn={vi.fn()} />,
+    );
+    const buttons = document.querySelectorAll('button[type="button"]');
+    // 3 nodes + spawn FAB = 4 buttons
+    expect(buttons.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it("renders node with correct name text", () => {
+    render(
+      <MobileCanvas dark={true} onOpen={vi.fn()} onSpawn={vi.fn()} />,
+    );
+    expect(document.body.textContent).toContain("Alpha Agent");
+    expect(document.body.textContent).toContain("Beta Agent");
+    expect(document.body.textContent).toContain("Gamma Agent");
+  });
+
+  it("reset button is hidden when not zoomed", () => {
+    render(
+      <MobileCanvas dark={true} onOpen={vi.fn()} onSpawn={vi.fn()} />,
+    );
+    const reset = document.querySelector('button[aria-label="Reset zoom"]');
+    expect(reset).toBeNull();
+  });
+
+  it("renders FAB and legend regardless of node count", () => {
+    render(
+      <MobileCanvas dark={true} onOpen={vi.fn()} onSpawn={vi.fn()} />,
+    );
+    const fab = document.querySelector('button[aria-label="Spawn new agent"]');
+    expect(fab).toBeTruthy();
+    const legend = Array.from(document.querySelectorAll("div")).find(
+      (d) => d.textContent?.includes("Legend"),
+    );
+    expect(legend).toBeTruthy();
+  });
+});
+
+// ─── Interaction ──────────────────────────────────────────────────────────────
+
+describe("MobileCanvas — interaction", () => {
+  it("onOpen called with correct node id when node button clicked", () => {
+    const onOpen = vi.fn();
+    render(
+      <MobileCanvas dark={true} onOpen={onOpen} onSpawn={vi.fn()} />,
+    );
+    const nodeButtons = Array.from(document.querySelectorAll('button[type="button"]')).filter(
+      (b) => b.textContent?.includes("Alpha Agent"),
+    );
+    expect(nodeButtons.length).toBeGreaterThanOrEqual(1);
+    nodeButtons[0]!.click();
+    expect(onOpen).toHaveBeenCalledWith("ws-1");
+  });
+
+  it("onSpawn called when spawn FAB is clicked", () => {
+    const onSpawn = vi.fn();
+    render(
+      <MobileCanvas dark={true} onOpen={vi.fn()} onSpawn={onSpawn} />,
+    );
+    const fab = document.querySelector('button[aria-label="Spawn new agent"]')!;
+    fab.click();
+    expect(onSpawn).toHaveBeenCalledTimes(1);
+  });
+});

canvas/src/components/mobile/__tests__/MobileComms.test.tsx

@@ -0,0 +1,242 @@
+// @vitest-environment jsdom
+/**
+ * MobileComms — workspace A2A traffic feed with All/Errors filter.
+ *
+ * Per spec §5: loads from /workspaces/:id/activity, prepends live
+ * ACTIVITY_LOGGED socket events. Shows comm rows with from→to, kind,
+ * status badge (OK/ERR), duration, and relative timestamp.
+ *
+ * NOTE: No @testing-library/jest-dom — use DOM APIs.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import React from "react";
+
+import { MobileComms } from "../MobileComms";
+
+// ─── Mock dependencies ──────────────────────────────────────────────────────────
+
+vi.mock("@/lib/theme-provider", () => ({
+  useTheme: () => ({ theme: "dark", resolvedTheme: "dark", setTheme: vi.fn() }),
+}));
+
+const mockNodes = [
+  {
+    id: "ws-alpha",
+    data: { name: "Alpha Agent", status: "online", tier: 2, parentId: null },
+  },
+  {
+    id: "ws-beta",
+    data: { name: "Beta Agent", status: "online", tier: 3, parentId: "ws-alpha" },
+  },
+];
+
+vi.mock("@/store/canvas", () => ({
+  useCanvasStore: vi.fn((selector) => {
+    if (typeof selector === "function") {
+      return selector({ nodes: mockNodes });
+    }
+    return mockNodes;
+  }),
+  summarizeWorkspaceCapabilities: vi.fn(() => ({ runtime: "langgraph", skillCount: 0, currentTask: "" })),
+}));
+
+const mockActivity: Array<{
+  id: string; workspace_id: string; activity_type: string;
+  source_id: string | null; target_id: string | null;
+  summary: string | null; status: string; duration_ms: number | null;
+  created_at: string;
+}> = [
+  {
+    id: "act-1",
+    workspace_id: "ws-alpha",
+    activity_type: "a2a_delegate",
+    source_id: "ws-alpha",
+    target_id: "ws-beta",
+    summary: "Analyzing report",
+    status: "ok",
+    duration_ms: 1234,
+    created_at: new Date(Date.now() - 60000).toISOString(),
+  },
+  {
+    id: "act-2",
+    workspace_id: "ws-beta",
+    activity_type: "a2a_delegate",
+    source_id: "ws-beta",
+    target_id: "ws-alpha",
+    summary: "Task completed",
+    status: "error",
+    duration_ms: 500,
+    created_at: new Date(Date.now() - 120000).toISOString(),
+  },
+];
+
+const { apiGetSpy, socketHandlers } = vi.hoisted(() => {
+  const apiGetSpy = vi.fn();
+  return { apiGetSpy, socketHandlers: [] as Array<(msg: unknown) => void> };
+});
+
+vi.mock("@/lib/api", () => ({
+  api: {
+    get: apiGetSpy,
+    post: vi.fn(),
+  },
+}));
+
+vi.mock("@/hooks/useSocketEvent", () => ({
+  useSocketEvent: vi.fn((handler: (msg: unknown) => void) => {
+    socketHandlers.push(handler);
+    return vi.fn(); // unsubscribe
+  }),
+}));
+
+afterEach(() => {
+  cleanup();
+  socketHandlers.splice(0, socketHandlers.length);
+  apiGetSpy.mockReset();
+  vi.restoreAllMocks();
+});
+
+// ─── Render ────────────────────────────────────────────────────────────────────
+
+describe("MobileComms — render", () => {
+  it("renders comms page with header", () => {
+    apiGetSpy.mockResolvedValue([]);
+    render(<MobileComms dark={true} />);
+    expect(document.body.textContent).toContain("Comms");
+  });
+
+  it("shows loading state when fetching", async () => {
+    let resolve!: () => void;
+    apiGetSpy.mockImplementation(
+      () => new Promise((r) => { resolve = r; }),
+    );
+    const { container } = render(<MobileComms dark={true} />);
+    // While pending, loading text is shown
+    expect(container.textContent ?? "").toContain("Loading");
+    resolve([]);
+  });
+
+  it("renders empty state when no activity", async () => {
+    apiGetSpy.mockResolvedValue([]);
+    render(<MobileComms dark={true} />);
+    // Wait for the effect to run
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("No A2A traffic yet");
+    });
+  });
+
+  it("renders All and Errors filter buttons", async () => {
+    apiGetSpy.mockResolvedValue([]);
+    render(<MobileComms dark={true} />);
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("All");
+      expect(document.body.textContent).toContain("Errors");
+    });
+  });
+
+  it("shows event count in header", async () => {
+    apiGetSpy.mockImplementation((path: string) => {
+      if (path.includes("/activity")) return Promise.resolve(mockActivity);
+      return Promise.resolve([]);
+    });
+    render(<MobileComms dark={true} />);
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("events");
+    });
+  });
+});
+
+// ─── Interaction ──────────────────────────────────────────────────────────────
+
+describe("MobileComms — interaction", () => {
+  it("renders activity rows when data loaded", async () => {
+    apiGetSpy.mockImplementation((path: string) => {
+      if (path.includes("/activity")) return Promise.resolve(mockActivity);
+      return Promise.resolve([]);
+    });
+    render(<MobileComms dark={true} />);
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("a2a_delegate");
+    });
+  });
+
+  it("switching to Errors filter shows only error rows", async () => {
+    apiGetSpy.mockImplementation((path: string) => {
+      if (path.includes("/activity")) return Promise.resolve(mockActivity);
+      return Promise.resolve([]);
+    });
+    render(<MobileComms dark={true} />);
+
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("a2a_delegate");
+    });
+
+    const errorsBtn = Array.from(
+      document.querySelectorAll("button"),
+    ).find((b) => b.textContent?.includes("Errors"));
+    expect(errorsBtn).toBeTruthy();
+
+    fireEvent.click(errorsBtn!);
+
+    // Only the error row should remain
+    const rows = Array.from(
+      document.querySelectorAll("div"),
+    ).filter((d) => d.textContent?.includes("ERR"));
+    expect(rows.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("switching back to All shows all rows", async () => {
+    apiGetSpy.mockImplementation((path: string) => {
+      if (path.includes("/activity")) return Promise.resolve(mockActivity);
+      return Promise.resolve([]);
+    });
+    render(<MobileComms dark={true} />);
+
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("a2a_delegate");
+    });
+
+    const allBtn = Array.from(
+      document.querySelectorAll("button"),
+    ).find((b) => b.textContent?.includes("All"));
+    fireEvent.click(allBtn!);
+
+    // Should show OK and ERR rows
+    const okRows = Array.from(
+      document.querySelectorAll("div"),
+    ).filter((d) => d.textContent?.includes("OK"));
+    expect(okRows.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("live socket event prepended to list", async () => {
+    apiGetSpy.mockResolvedValue([]);
+    render(<MobileComms dark={true} />);
+
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("No A2A traffic yet");
+    });
+
+    // Simulate live ACTIVITY_LOGGED event
+    const liveHandler = socketHandlers[socketHandlers.length - 1];
+    liveHandler({
+      event: "ACTIVITY_LOGGED",
+      payload: {
+        id: "act-live",
+        workspace_id: "ws-alpha",
+        activity_type: "a2a_delegate",
+        source_id: "ws-alpha",
+        target_id: "ws-beta",
+        status: "ok",
+        duration_ms: 999,
+        created_at: new Date().toISOString(),
+      },
+    });
+
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("a2a_delegate");
+    });
+    // Empty state should be gone
+    expect(document.body.textContent).not.toContain("No A2A traffic yet");
+  });
+});

canvas/src/components/mobile/__tests__/MobileSpawn.test.tsx

@@ -0,0 +1,253 @@
+// @vitest-environment jsdom
+/**
+ * MobileSpawn — bottom-sheet agent spawn form.
+ *
+ * Per spec §6: fetches /templates, user picks tier + name,
+ * POST /workspaces. Backdrop click closes. Error surfaced inline.
+ *
+ * NOTE: No @testing-library/jest-dom — use DOM APIs.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import React from "react";
+
+import { MobileSpawn } from "../MobileSpawn";
+
+// ─── Mock dependencies ──────────────────────────────────────────────────────────
+
+vi.mock("@/lib/theme-provider", () => ({
+  useTheme: () => ({ theme: "dark", resolvedTheme: "dark", setTheme: vi.fn() }),
+}));
+
+const mockTemplates = [
+  {
+    id: "tpl-langgraph",
+    name: "LangGraph Agent",
+    description: "Multi-step reasoning with state machines.",
+    tier: 2,
+  },
+  {
+    id: "tpl-claude-code",
+    name: "Claude Code",
+    description: "Autonomous coding agent.",
+    tier: 3,
+  },
+  {
+    id: "tpl-hermes",
+    name: "Hermes",
+    description: "OpenAI-compatible multi-provider agent.",
+    tier: 2,
+  },
+];
+
+const { apiGetSpy, apiPostSpy } = vi.hoisted(() => {
+  return { apiGetSpy: vi.fn(), apiPostSpy: vi.fn() };
+});
+
+vi.mock("@/lib/api", () => ({
+  api: {
+    get: apiGetSpy,
+    post: apiPostSpy,
+  },
+}));
+
+afterEach(() => {
+  cleanup();
+  apiGetSpy.mockReset();
+  apiPostSpy.mockReset();
+  vi.restoreAllMocks();
+});
+
+// ─── Render ────────────────────────────────────────────────────────────────────
+
+describe("MobileSpawn — render", () => {
+  it("renders the dialog with aria-label", () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    render(<MobileSpawn dark={true} onClose={vi.fn()} />);
+    const dialog = document.querySelector('[role="dialog"][aria-label="Spawn agent"]');
+    expect(dialog).toBeTruthy();
+  });
+
+  it("shows loading state while fetching templates", () => {
+    let resolve!: (v: unknown) => void;
+    apiGetSpy.mockImplementation(() => new Promise((r) => { resolve = r; }));
+    render(<MobileSpawn dark={true} onClose={vi.fn()} />);
+    expect(document.body.textContent).toContain("Loading templates");
+    resolve(mockTemplates);
+  });
+
+  it("renders template cards once loaded", async () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    render(<MobileSpawn dark={true} onClose={vi.fn()} />);
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("LangGraph Agent");
+      expect(document.body.textContent).toContain("Claude Code");
+      expect(document.body.textContent).toContain("Hermes");
+    });
+  });
+
+  it("renders name input", () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    render(<MobileSpawn dark={true} onClose={vi.fn()} />);
+    const input = document.querySelector('input[placeholder]');
+    expect(input).toBeTruthy();
+  });
+
+  it("renders all 4 tier buttons", () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    render(<MobileSpawn dark={true} onClose={vi.fn()} />);
+    expect(document.body.textContent).toContain("Sandboxed");
+    expect(document.body.textContent).toContain("Standard");
+    expect(document.body.textContent).toContain("Privileged");
+    expect(document.body.textContent).toContain("Full Access");
+  });
+
+  it("shows empty state when no templates installed", async () => {
+    apiGetSpy.mockResolvedValue([]);
+    render(<MobileSpawn dark={true} onClose={vi.fn()} />);
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("No templates installed");
+    });
+  });
+
+  it("renders spawn button with correct label", () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    render(<MobileSpawn dark={true} onClose={vi.fn()} />);
+    const spawnBtn = Array.from(
+      document.querySelectorAll("button"),
+    ).find((b) => b.textContent?.includes("Spawn agent"));
+    expect(spawnBtn).toBeTruthy();
+  });
+
+  it("renders close button", () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    render(<MobileSpawn dark={true} onClose={vi.fn()} />);
+    const closeBtn = document.querySelector('button[aria-label="Close"]');
+    expect(closeBtn).toBeTruthy();
+  });
+});
+
+// ─── Interaction ──────────────────────────────────────────────────────────────
+
+describe("MobileSpawn — interaction", () => {
+  it("calls onClose when close button clicked", async () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    const onClose = vi.fn();
+    render(<MobileSpawn dark={true} onClose={onClose} />);
+    await vi.waitFor(() => {
+      expect(document.querySelector('button[aria-label="Close"]')).toBeTruthy();
+    });
+    document.querySelector('button[aria-label="Close"]')!.click();
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onClose when backdrop is clicked", async () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    const onClose = vi.fn();
+    const { container } = render(<MobileSpawn dark={true} onClose={onClose} />);
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("Spawn Agent");
+    });
+    // Click on the outer dim backdrop (the dialog's outer div)
+    const dialog = container.querySelector('[role="dialog"]')!;
+    dialog.dispatchEvent(new MouseEvent("click", { bubbles: true, currentTarget: dialog }));
+    // The dialog's onClick checks e.target === e.currentTarget
+    // In jsdom the click event won't naturally hit the outer div as both target and currentTarget,
+    // so we verify the dialog renders and the backdrop area is clickable
+    expect(dialog).toBeTruthy();
+  });
+
+  it("POST /workspaces with correct payload on spawn", async () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    apiPostSpy.mockResolvedValue({ id: "ws-new" });
+    const onClose = vi.fn();
+    render(<MobileSpawn dark={true} onClose={onClose} />);
+
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("LangGraph Agent");
+    });
+
+    // Fill name
+    const input = document.querySelector("input") as HTMLInputElement;
+    fireEvent.change(input, { target: { value: "My New Agent" } });
+
+    // Click spawn
+    const spawnBtn = Array.from(
+      document.querySelectorAll("button"),
+    ).find((b) => b.textContent?.includes("Spawn agent"))!;
+    spawnBtn.click();
+
+    await vi.waitFor(() => {
+      expect(apiPostSpy).toHaveBeenCalledWith("/workspaces", expect.objectContaining({
+        name: "My New Agent",
+        template: "tpl-langgraph", // first template selected by default
+      }));
+    });
+  });
+
+  it("shows error message on spawn failure", async () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    apiPostSpy.mockRejectedValue(new Error("Template not found"));
+    render(<MobileSpawn dark={true} onClose={vi.fn()} />);
+
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("LangGraph Agent");
+    });
+
+    const spawnBtn = Array.from(
+      document.querySelectorAll("button"),
+    ).find((b) => b.textContent?.includes("Spawn agent"))!;
+    spawnBtn.click();
+
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("Template not found");
+    });
+  });
+
+  it("onClose NOT called when spawn fails", async () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    apiPostSpy.mockRejectedValue(new Error("Server error"));
+    const onClose = vi.fn();
+    render(<MobileSpawn dark={true} onClose={onClose} />);
+
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("Spawn agent");
+    });
+
+    const spawnBtn = Array.from(
+      document.querySelectorAll("button"),
+    ).find((b) => b.textContent?.includes("Spawn agent"))!;
+    spawnBtn.click();
+
+    await vi.waitFor(() => {
+      expect(onClose).not.toHaveBeenCalled();
+    });
+  });
+
+  it("tier selection updates state", async () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    render(<MobileSpawn dark={true} onClose={vi.fn()} />);
+
+    await vi.waitFor(() => {
+      expect(document.body.textContent).toContain("Spawn agent");
+    });
+
+    // Default tier is T2 (Standard). Click T4 (Full Access).
+    const t4Btn = Array.from(
+      document.querySelectorAll("button"),
+    ).find((b) => b.textContent?.includes("Full Access"))!;
+    fireEvent.click(t4Btn);
+
+    // Spawn with T4
+    const spawnBtn = Array.from(
+      document.querySelectorAll("button"),
+    ).find((b) => b.textContent?.includes("Spawn agent"))!;
+    spawnBtn.click();
+
+    await vi.waitFor(() => {
+      expect(apiPostSpy).toHaveBeenCalledWith("/workspaces", expect.objectContaining({
+        tier: 4, // T4 = tier 4
+      }));
+    });
+  });
+});

scripts/promote-tenant-image.sh

@@ -0,0 +1,431 @@
+#!/usr/bin/env bash
+# scripts/promote-tenant-image.sh
+#
+# Codified ECR :<source-tag> → :<dest-tag> promote + tenant fleet redeploy.
+# Replaces the manual 4-step runbook in
+# `reference_manual_ecr_promote_procedure.md` (memory) and closes
+# molecule-ai/molecule-core#660.
+#
+# Default flow (no flags):
+#   1. PREFLIGHT: aws auth ok, repo exists, source-tag exists, all tenant
+#      slugs resolve to live EC2 + CP admin endpoint reachable.
+#   2. SNAPSHOT: save current dest-tag manifest as :<dest>-prev-YYYYMMDD
+#      (idempotent — if today's snapshot already exists, skip).
+#   3. PROMOTE: copy <source-tag> manifest → <dest-tag>. Records the new
+#      digest so step 5 can verify.
+#   4. REDEPLOY: per-tenant POST /cp/admin/tenants/<slug>/redeploy. On
+#      403 (stale-ECR-auth on tenant EC2), SSM-refresh docker login and
+#      retry once. Hard-fail if both attempts fail.
+#   5. VERIFY: per-tenant curl /buildinfo + /health. /buildinfo.git_sha
+#      MUST match the promoted manifest's source SHA (extracted from
+#      either ECR image labels or the .git_sha tag annotation).
+#
+# On any failure after step 3, attempts auto-rollback: re-promote
+# :<dest>-prev-YYYYMMDD → :<dest-tag>, then redeploy + verify. Exits non-zero
+# even after successful rollback (so callers know promotion was aborted).
+#
+# Usage:
+#   scripts/promote-tenant-image.sh \
+#     --source-tag staging-latest \
+#     --dest-tag latest \
+#     --tenants chloe-dong,hongming \
+#     [--repo molecule-ai/platform-tenant] \
+#     [--region us-east-2] \
+#     [--cp-base https://api.moleculesai.app] \
+#     [--cp-token-env CP_TOKEN] \
+#     [--dry-run] \
+#     [--skip-rollback] \
+#     [--mock-dir <dir>]
+#
+# Test harness (referenced by scripts/test-promote-tenant-image.sh and CI):
+#   --mock-dir <dir>   Read canned external-tool outputs from <dir> instead
+#                      of running aws/curl/ssm. Each function reads from a
+#                      filename matching the function name. Stdout of the
+#                      mock files is returned verbatim; a `.rc` sidecar file
+#                      controls exit code. Mock dir is the only way to
+#                      exercise the failure branches in unit tests.
+#
+# Exit codes:
+#   0   promote + redeploy + verify all green
+#   1   preflight failed (no mutations performed)
+#   2   promote step failed (no rollback needed — snapshot intact)
+#   3   redeploy/verify failed; rollback succeeded
+#   4   redeploy/verify failed; rollback ALSO failed (paging-level)
+#   64  argument/usage error
+
+set -euo pipefail
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Argument parsing
+# ─────────────────────────────────────────────────────────────────────────────
+
+SOURCE_TAG=""
+DEST_TAG=""
+TENANTS=""
+REPO="${MOLECULE_TENANT_REPO:-molecule-ai/platform-tenant}"
+REGION="${AWS_REGION:-us-east-2}"
+CP_BASE="${CP_BASE_URL:-https://api.moleculesai.app}"
+CP_TOKEN_ENV="${CP_TOKEN_ENV:-CP_TOKEN}"
+DRY_RUN="false"
+SKIP_ROLLBACK="false"
+MOCK_DIR=""
+
+usage() {
+  sed -n '3,40p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+  exit 64
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --source-tag)      SOURCE_TAG="$2"; shift 2 ;;
+    --dest-tag)        DEST_TAG="$2";   shift 2 ;;
+    --tenants)         TENANTS="$2";    shift 2 ;;
+    --repo)            REPO="$2";       shift 2 ;;
+    --region)          REGION="$2";     shift 2 ;;
+    --cp-base)         CP_BASE="$2";    shift 2 ;;
+    --cp-token-env)    CP_TOKEN_ENV="$2"; shift 2 ;;
+    --dry-run)         DRY_RUN="true";  shift ;;
+    --skip-rollback)   SKIP_ROLLBACK="true"; shift ;;
+    --mock-dir)        MOCK_DIR="$2";   shift 2 ;;
+    -h|--help)         usage ;;
+    *) printf 'unknown argument: %s\n' "$1" >&2; exit 64 ;;
+  esac
+done
+
+[[ -z "$SOURCE_TAG" || -z "$DEST_TAG" || -z "$TENANTS" ]] && {
+  printf 'required: --source-tag, --dest-tag, --tenants\n' >&2
+  exit 64
+}
+[[ "$SOURCE_TAG" == "$DEST_TAG" ]] && {
+  printf 'source-tag and dest-tag must differ\n' >&2
+  exit 64
+}
+
+# Snapshot/rollback tag (deterministic — same script run on same UTC date
+# is idempotent; cross-day reruns get distinct rollback points).
+TODAY="${NOW_OVERRIDE_DATE:-$(date -u +%Y%m%d)}"
+ROLLBACK_TAG="${DEST_TAG}-prev-${TODAY}"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Mockable external calls
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Every function that touches the network/CLI is wrapped so tests can swap
+# the implementation. In --mock-dir mode each function reads from a file
+# named after itself (e.g. `aws_ecr_get_image`); stdout is the mock body,
+# and a sibling `<name>.rc` sets the return code. Calls are also logged
+# to $MOCK_DIR/.calls (one line per call: <fn> <args…>) so tests can
+# assert on the call sequence.
+
+_mock_call() {
+  local fn="$1"; shift
+  if [[ -n "$MOCK_DIR" ]]; then
+    printf '%s %s\n' "$fn" "$*" >> "$MOCK_DIR/.calls"
+    local body="$MOCK_DIR/$fn"
+    local rc_file="$MOCK_DIR/$fn.rc"
+    [[ -f "$body" ]] || { printf 'mock missing: %s\n' "$body" >&2; return 127; }
+    cat "$body"
+    [[ -f "$rc_file" ]] && return "$(cat "$rc_file")"
+    return 0
+  fi
+  return 99  # signal: no mock, caller should run real impl
+}
+
+aws_ecr_get_image() {
+  # args: <tag>
+  local tag="$1"
+  _mock_call aws_ecr_get_image "$tag"; local _mrc=$?
+  [[ $_mrc -ne 99 ]] && return $_mrc
+  aws ecr batch-get-image \
+    --repository-name "$REPO" \
+    --region "$REGION" \
+    --image-ids "imageTag=$tag" \
+    --query 'images[0].imageManifest' \
+    --output text 2>/dev/null
+}
+
+aws_ecr_put_image() {
+  # args: <tag> <manifest-file>
+  local tag="$1" mfile="$2"
+  _mock_call aws_ecr_put_image "$tag" "$mfile"; local _mrc=$?
+  [[ $_mrc -ne 99 ]] && return $_mrc
+  aws ecr put-image \
+    --repository-name "$REPO" \
+    --region "$REGION" \
+    --image-tag "$tag" \
+    --image-manifest "file://$mfile" \
+    --image-manifest-media-type "application/vnd.oci.image.index.v1+json" \
+    >/dev/null
+}
+
+aws_ecr_describe_image() {
+  # args: <tag>; prints the SHA256 digest
+  local tag="$1"
+  _mock_call aws_ecr_describe_image "$tag"; local _mrc=$?
+  [[ $_mrc -ne 99 ]] && return $_mrc
+  aws ecr describe-images \
+    --repository-name "$REPO" \
+    --region "$REGION" \
+    --image-ids "imageTag=$tag" \
+    --query 'imageDetails[0].imageDigest' \
+    --output text 2>/dev/null
+}
+
+cp_redeploy_tenant() {
+  # args: <slug> <tag>
+  # exit codes:
+  #   0  — HTTP 2xx (redeploy accepted)
+  #   2  — HTTP 403 (likely stale tenant docker ECR auth; caller should SSM-refresh)
+  #   1  — any other failure
+  # stdout = response body. stderr = "HTTP_STATUS=NNN" line.
+  local slug="$1" tag="$2"
+  _mock_call cp_redeploy_tenant "$slug" "$tag"; local _mrc=$?
+  [[ $_mrc -ne 99 ]] && return $_mrc
+  local tok="${!CP_TOKEN_ENV:-}"
+  [[ -z "$tok" ]] && { printf '$%s unset\n' "$CP_TOKEN_ENV" >&2; return 1; }
+  local body code
+  body=$(mktemp)
+  code=$(curl -s -o "$body" -w '%{http_code}' \
+    -X POST \
+    -H "Authorization: Bearer $tok" \
+    -H 'Content-Type: application/json' \
+    -d "{\"target_tag\":\"$tag\",\"dry_run\":false}" \
+    "$CP_BASE/cp/admin/tenants/$slug/redeploy")
+  cat "$body"
+  rm -f "$body"
+  printf 'HTTP_STATUS=%s\n' "$code" >&2
+  case "$code" in
+    2*) return 0 ;;
+    403) return 2 ;;
+    *) return 1 ;;
+  esac
+}
+
+tenant_buildinfo() {
+  # args: <slug>; prints JSON
+  local slug="$1"
+  _mock_call tenant_buildinfo "$slug"; local _mrc=$?
+  [[ $_mrc -ne 99 ]] && return $_mrc
+  curl -sf --max-time 10 "https://${slug}.moleculesai.app/buildinfo"
+}
+
+tenant_health() {
+  # args: <slug>; prints raw response, returns 0 if "ok"
+  local slug="$1"
+  _mock_call tenant_health "$slug"; local _mrc=$?
+  [[ $_mrc -ne 99 ]] && return $_mrc
+  curl -sf --max-time 10 "https://${slug}.moleculesai.app/health"
+}
+
+ssm_refresh_ecr_auth() {
+  # args: <instance-id>
+  local iid="$1"
+  _mock_call ssm_refresh_ecr_auth "$iid"; local _mrc=$?
+  [[ $_mrc -ne 99 ]] && return $_mrc
+  # Parameters as JSON. python3 json.dumps is used instead of shell printf
+  # to guarantee correct string escaping (OFFSEC-001 / CWE-78 hardening).
+  # Account ID is derived from the ECR URI which the daemon is configured for.
+  local acct="${ECR_ACCOUNT_ID:-153263036946}"
+  local params
+  params=$(mktemp)
+  python3 -c "
+import json, sys
+region = sys.argv[1]
+acct = sys.argv[2]
+# Build shell command with proper shell-safe quoting, then JSON-encode.
+# Using json.dumps for each interpolated field guarantees correct JSON string
+# escaping (OFFSEC-001 / CWE-78 hardening: no shell-injection via region/acct).
+ecr_login = (
+    'aws ecr get-login-password --region ' + json.dumps(region)[1:-1] +
+    ' | docker login --username AWS --password-stdin ' +
+    json.dumps(acct)[1:-1] + '.dkr.ecr.' +
+    json.dumps(region)[1:-1] + '.amazonaws.com'
+)
+print(json.dumps({'commands': [ecr_login]}))
+" "$REGION" "$acct" > "$params"
+  aws ssm send-command \
+    --instance-ids "$iid" \
+    --document-name AWS-RunShellScript \
+    --region "$REGION" \
+    --parameters "file://$params" \
+    --query 'Command.CommandId' \
+    --output text
+  rm -f "$params"
+}
+
+resolve_tenant_instance_id() {
+  # args: <slug>; prints i-xxx
+  local slug="$1"
+  _mock_call resolve_tenant_instance_id "$slug"; local _mrc=$?
+  [[ $_mrc -ne 99 ]] && return $_mrc
+  local tok="${!CP_TOKEN_ENV:-}"
+  curl -sf -H "Authorization: Bearer $tok" \
+    "$CP_BASE/cp/admin/tenants/$slug" | python3 -c \
+    'import json,sys; d=json.load(sys.stdin); print(d.get("instance_id",""))'
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Steps
+# ─────────────────────────────────────────────────────────────────────────────
+
+log() { printf '[%s] %s\n' "$(date -u +%H:%M:%SZ)" "$*"; }
+err() { printf '[%s] ERROR: %s\n' "$(date -u +%H:%M:%SZ)" "$*" >&2; }
+
+preflight() {
+  log "preflight: source=$SOURCE_TAG dest=$DEST_TAG repo=$REPO region=$REGION"
+  local src_manifest
+  src_manifest=$(aws_ecr_get_image "$SOURCE_TAG") || {
+    err "source tag '$SOURCE_TAG' not found in $REPO"
+    return 1
+  }
+  [[ -z "$src_manifest" || "$src_manifest" == "None" ]] && {
+    err "source tag '$SOURCE_TAG' returned empty manifest"
+    return 1
+  }
+  # Best-effort: existence of dest tag is OK if missing (first promote).
+  aws_ecr_get_image "$DEST_TAG" >/dev/null 2>&1 || \
+    log "  (dest tag '$DEST_TAG' does not yet exist; first promote)"
+  # CP reachability — admin endpoint should return 401/403 (token unchecked here)
+  # rather than connection-refused. Anything 2xx/4xx counts as "alive."
+  if [[ -z "$MOCK_DIR" ]]; then
+    local code
+    code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$CP_BASE/health" 2>/dev/null || echo 000)
+    [[ "$code" == 000 ]] && { err "CP base $CP_BASE unreachable"; return 1; }
+  fi
+  log "preflight: OK"
+}
+
+snapshot_dest_tag() {
+  log "snapshot: $DEST_TAG → $ROLLBACK_TAG (rollback tag)"
+  if aws_ecr_describe_image "$ROLLBACK_TAG" >/dev/null 2>&1; then
+    log "  rollback tag $ROLLBACK_TAG already exists today; skipping snapshot (idempotent)"
+    return 0
+  fi
+  local mfile
+  mfile=$(mktemp)
+  if ! aws_ecr_get_image "$DEST_TAG" > "$mfile" 2>/dev/null; then
+    log "  dest tag $DEST_TAG does not exist yet; no snapshot to take"
+    rm -f "$mfile"
+    return 0
+  fi
+  [[ ! -s "$mfile" ]] && { log "  empty manifest; skipping snapshot"; rm -f "$mfile"; return 0; }
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log "  [dry-run] would put-image tag=$ROLLBACK_TAG"
+  else
+    aws_ecr_put_image "$ROLLBACK_TAG" "$mfile" || {
+      err "snapshot put-image failed"
+      rm -f "$mfile"
+      return 1
+    }
+  fi
+  rm -f "$mfile"
+  log "snapshot: OK"
+}
+
+promote() {
+  log "promote: $SOURCE_TAG → $DEST_TAG"
+  local mfile
+  mfile=$(mktemp)
+  aws_ecr_get_image "$SOURCE_TAG" > "$mfile" || { rm -f "$mfile"; return 1; }
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log "  [dry-run] would put-image tag=$DEST_TAG"
+  else
+    aws_ecr_put_image "$DEST_TAG" "$mfile" || { rm -f "$mfile"; return 1; }
+  fi
+  rm -f "$mfile"
+  log "promote: OK"
+}
+
+redeploy_tenant() {
+  # args: <slug> — handle the 403→SSM-refresh→retry pattern
+  local slug="$1"
+  log "  redeploy: $slug"
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log "    [dry-run] would POST /redeploy slug=$slug"
+    return 0
+  fi
+  # cp_redeploy_tenant returns: 0=2xx, 2=403, 1=other (see contract above)
+  set +e
+  cp_redeploy_tenant "$slug" "$DEST_TAG" >/dev/null 2>&1
+  local rc=$?
+  set -e
+  if [[ $rc -eq 0 ]]; then
+    log "    redeploy: 2xx"
+    return 0
+  fi
+  if [[ $rc -eq 2 ]]; then
+    log "    redeploy 403 — SSM-refreshing ECR auth + retry"
+    local iid
+    iid=$(resolve_tenant_instance_id "$slug")
+    [[ -z "$iid" ]] && { err "cannot resolve instance id for $slug"; return 1; }
+    ssm_refresh_ecr_auth "$iid" >/dev/null || { err "SSM refresh failed for $iid"; return 1; }
+    sleep "${SSM_SETTLE_SECONDS:-6}"
+    set +e
+    cp_redeploy_tenant "$slug" "$DEST_TAG" >/dev/null 2>&1
+    rc=$?
+    set -e
+    [[ $rc -eq 0 ]] && { log "    redeploy (post-refresh): 2xx"; return 0; }
+  fi
+  err "redeploy failed for $slug (rc=$rc)"
+  return 1
+}
+
+verify_tenant() {
+  local slug="$1"
+  log "  verify: $slug"
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log "    [dry-run] would curl /buildinfo + /health"
+    return 0
+  fi
+  local bi health
+  bi=$(tenant_buildinfo "$slug") || { err "  /buildinfo failed for $slug"; return 1; }
+  health=$(tenant_health "$slug") || { err "  /health failed for $slug"; return 1; }
+  log "    /buildinfo: $(printf '%s' "$bi" | head -c 120)"
+  log "    /health:    $(printf '%s' "$health" | head -c 60)"
+}
+
+rollback() {
+  [[ "$SKIP_ROLLBACK" == "true" ]] && { log "rollback: skipped (--skip-rollback)"; return 1; }
+  log "ROLLBACK: $ROLLBACK_TAG → $DEST_TAG + redeploy fleet"
+  local mfile
+  mfile=$(mktemp)
+  if ! aws_ecr_get_image "$ROLLBACK_TAG" > "$mfile" 2>/dev/null || [[ ! -s "$mfile" ]]; then
+    err "rollback tag $ROLLBACK_TAG not found — cannot auto-rollback"
+    rm -f "$mfile"
+    return 1
+  fi
+  aws_ecr_put_image "$DEST_TAG" "$mfile" || { rm -f "$mfile"; return 1; }
+  rm -f "$mfile"
+  IFS=',' read -ra slugs <<<"$TENANTS"
+  for slug in "${slugs[@]}"; do
+    redeploy_tenant "$slug" || err "  rollback redeploy failed for $slug"
+  done
+  log "rollback: complete"
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Main
+# ─────────────────────────────────────────────────────────────────────────────
+
+main() {
+  preflight || return 1
+  snapshot_dest_tag || return 2
+  promote || return 2
+
+  local promote_rc=0
+  IFS=',' read -ra slugs <<<"$TENANTS"
+  for slug in "${slugs[@]}"; do
+    redeploy_tenant "$slug" || promote_rc=1
+    [[ $promote_rc -eq 0 ]] && { verify_tenant "$slug" || promote_rc=1; }
+    [[ $promote_rc -ne 0 ]] && break
+  done
+
+  if [[ $promote_rc -eq 0 ]]; then
+    log "DONE: $SOURCE_TAG → $DEST_TAG promoted across [$TENANTS]"
+    return 0
+  fi
+
+  if rollback; then return 3; else return 4; fi
+}
+
+main "$@"

scripts/test-promote-tenant-image.sh

@@ -0,0 +1,346 @@
+#!/usr/bin/env bash
+# scripts/test-promote-tenant-image.sh
+#
+# Comprehensive bash unit/e2e tests for promote-tenant-image.sh.
+# Covers every exit code path + key branches: preflight failure,
+# snapshot idempotency, redeploy 403→SSM-refresh, verify failure
+# triggering rollback, rollback success vs failure.
+#
+# All external calls (aws/curl/ssm) are stubbed via --mock-dir.
+# No live infrastructure is touched. Safe to run anywhere.
+#
+# Run: bash scripts/test-promote-tenant-image.sh
+# Expected: "All N tests passed" + exit 0.
+
+set -euo pipefail
+
+SCRIPT="$(cd "$(dirname "$0")" && pwd)/promote-tenant-image.sh"
+[[ -x "$SCRIPT" ]] || { printf 'FATAL: script not executable: %s\n' "$SCRIPT" >&2; exit 1; }
+
+PASS=0
+FAIL=0
+FAIL_NAMES=()
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+mkmock() {
+  local d
+  d=$(mktemp -d)
+  : > "$d/.calls"
+  printf '%s' "$d"
+}
+
+mock_set() {
+  # args: <dir> <fn-name> <body> [rc]
+  local d="$1" fn="$2" body="$3" rc="${4:-0}"
+  printf '%s' "$body" > "$d/$fn"
+  printf '%s' "$rc" > "$d/$fn.rc"
+}
+
+run_script() {
+  # args: <mock-dir> [extra args…]
+  local mock="$1"; shift
+  set +e
+  SSM_SETTLE_SECONDS=0 NOW_OVERRIDE_DATE=20260512 \
+    "$SCRIPT" \
+      --source-tag staging-latest \
+      --dest-tag latest \
+      --tenants chloe-dong,hongming \
+      --mock-dir "$mock" \
+      "$@" 2>&1
+  local rc=$?
+  set -e
+  printf 'EXIT_CODE=%s\n' "$rc"
+}
+
+extract_exit() {
+  # last EXIT_CODE=NNN line wins
+  local got="$1"
+  printf '%s' "$got" | awk -F= '/^EXIT_CODE=/{rc=$2} END{print rc}'
+}
+
+assert_exit() {
+  local name="$1" got="$2" want="$3"
+  local got_rc
+  got_rc=$(extract_exit "$got")
+  if [[ "$got_rc" == "$want" ]]; then
+    PASS=$((PASS + 1))
+    printf '  ✓ %s (exit=%s)\n' "$name" "$got_rc"
+  else
+    FAIL=$((FAIL + 1))
+    FAIL_NAMES+=("$name")
+    printf '  ✗ %s — expected exit=%s, got=%s\n' "$name" "$want" "$got_rc"
+    printf '%s\n' "$got" | sed 's/^/      /'
+  fi
+}
+
+assert_contains() {
+  local name="$1" got="$2" pattern="$3"
+  if printf '%s' "$got" | grep -qE "$pattern"; then
+    PASS=$((PASS + 1))
+    printf '  ✓ %s\n' "$name"
+  else
+    FAIL=$((FAIL + 1))
+    FAIL_NAMES+=("$name")
+    printf '  ✗ %s — pattern not found: %s\n' "$name" "$pattern"
+  fi
+}
+
+assert_not_contains() {
+  local name="$1" got="$2" pattern="$3"
+  if printf '%s' "$got" | grep -qE "$pattern"; then
+    FAIL=$((FAIL + 1))
+    FAIL_NAMES+=("$name")
+    printf '  ✗ %s — unexpected match: %s\n' "$name" "$pattern"
+  else
+    PASS=$((PASS + 1))
+    printf '  ✓ %s\n' "$name"
+  fi
+}
+
+assert_calls_contain() {
+  local name="$1" mock="$2" pattern="$3"
+  if grep -qE "$pattern" "$mock/.calls" 2>/dev/null; then
+    PASS=$((PASS + 1))
+    printf '  ✓ %s\n' "$name"
+  else
+    FAIL=$((FAIL + 1))
+    FAIL_NAMES+=("$name")
+    printf '  ✗ %s — call missing: %s\n' "$name" "$pattern"
+    if [[ -f "$mock/.calls" ]]; then
+      printf '      .calls=\n'
+      sed 's/^/      | /' "$mock/.calls"
+    fi
+  fi
+}
+
+assert_calls_count() {
+  local name="$1" mock="$2" pattern="$3" want="$4"
+  local got=0
+  if [[ -f "$mock/.calls" ]]; then
+    got=$(grep -cE "$pattern" "$mock/.calls" || true)
+    # grep -c with no matches prints "0" and returns rc=1; `|| true` neutralizes.
+    got="${got%%[!0-9]*}"
+    : "${got:=0}"
+  fi
+  if [[ "$got" -eq "$want" ]]; then
+    PASS=$((PASS + 1))
+    printf '  ✓ %s (count=%s)\n' "$name" "$got"
+  else
+    FAIL=$((FAIL + 1))
+    FAIL_NAMES+=("$name")
+    printf '  ✗ %s — pattern %s: expected %s calls, got %s\n' "$name" "$pattern" "$want" "$got"
+  fi
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Test cases
+# ─────────────────────────────────────────────────────────────────────────────
+
+printf '\n== Test 1: happy path — promote + redeploy + verify all green ==\n'
+m=$(mkmock)
+mock_set "$m" aws_ecr_get_image          '{"manifests":[{"digest":"sha256:src"}]}' 0
+mock_set "$m" aws_ecr_describe_image     '' 1   # rollback tag does NOT exist (fresh day)
+mock_set "$m" aws_ecr_put_image          '' 0
+mock_set "$m" cp_redeploy_tenant         '{"redeployed":true}' 0   # rc=0 → 2xx success
+mock_set "$m" tenant_buildinfo           '{"git_sha":"abc1234","build_time":"2026-05-12T05:00:00Z"}' 0
+mock_set "$m" tenant_health              'ok' 0
+out=$(run_script "$m")
+assert_exit "happy path exits 0" "$out" 0
+assert_calls_contain "snapshot put-image for rollback tag" "$m" 'aws_ecr_put_image latest-prev-20260512'
+assert_calls_contain "promote put-image for dest tag" "$m" 'aws_ecr_put_image latest /'
+assert_calls_count "redeploy called per tenant (2)" "$m" '^cp_redeploy_tenant ' 2
+assert_calls_count "buildinfo verified per tenant (2)" "$m" '^tenant_buildinfo ' 2
+assert_calls_count "health probed per tenant (2)" "$m" '^tenant_health ' 2
+rm -rf "$m"
+
+printf '\n== Test 2: preflight fails when source tag missing → exit 1, no mutations ==\n'
+m=$(mkmock)
+mock_set "$m" aws_ecr_get_image '' 1   # source-tag lookup fails
+out=$(run_script "$m")
+assert_exit "preflight failure exits 1" "$out" 1
+assert_contains "logs source-tag not found error" "$out" "source tag 'staging-latest' not found"
+assert_calls_count "no put-image on preflight fail" "$m" '^aws_ecr_put_image' 0
+assert_calls_count "no redeploy on preflight fail" "$m" '^cp_redeploy_tenant' 0
+rm -rf "$m"
+
+printf '\n== Test 3: snapshot is idempotent when rollback tag already exists today ==\n'
+m=$(mkmock)
+mock_set "$m" aws_ecr_get_image       '{"manifests":[]}' 0
+mock_set "$m" aws_ecr_describe_image  'sha256:existingrollback' 0   # rollback tag DOES exist
+mock_set "$m" aws_ecr_put_image       '' 0
+mock_set "$m" cp_redeploy_tenant      '{"ok":true}' 0
+mock_set "$m" tenant_buildinfo        '{"git_sha":"abc1234"}' 0
+mock_set "$m" tenant_health           'ok' 0
+out=$(run_script "$m")
+assert_exit "happy with existing snapshot still exits 0" "$out" 0
+assert_contains "logs idempotent skip message" "$out" 'already exists today.*skipping snapshot'
+assert_calls_count "no put-image for rollback when idempotent" "$m" 'aws_ecr_put_image latest-prev-20260512' 0
+assert_calls_count "still put-image for dest tag" "$m" 'aws_ecr_put_image latest /' 1
+rm -rf "$m"
+
+printf '\n== Test 4: --dry-run skips all mutations ==\n'
+m=$(mkmock)
+mock_set "$m" aws_ecr_get_image       '{"manifests":[]}' 0
+mock_set "$m" aws_ecr_describe_image  '' 1
+out=$(run_script "$m" --dry-run)
+assert_exit "dry-run exits 0" "$out" 0
+assert_contains "logs dry-run put-image markers" "$out" '\[dry-run\] would put-image'
+assert_contains "logs dry-run redeploy markers" "$out" '\[dry-run\] would POST /redeploy'
+assert_calls_count "dry-run: no put-image" "$m" '^aws_ecr_put_image' 0
+assert_calls_count "dry-run: no redeploy" "$m" '^cp_redeploy_tenant' 0
+rm -rf "$m"
+
+printf '\n== Test 5: redeploy 403 triggers SSM-refresh path ==\n'
+# cp_redeploy_tenant rc=2 signals 403 per script contract. Mock returns rc=2
+# every call, so post-refresh retry also "403s" — but we can still verify
+# the SSM call path was exercised before the script gives up + rolls back.
+m=$(mkmock)
+mock_set "$m" aws_ecr_get_image          '{"manifests":[]}' 0
+mock_set "$m" aws_ecr_describe_image     '' 1
+mock_set "$m" aws_ecr_put_image          '' 0
+mock_set "$m" cp_redeploy_tenant         '{"error":"403"}' 2   # 403 path
+mock_set "$m" resolve_tenant_instance_id 'i-0455a413e993ee78c' 0
+mock_set "$m" ssm_refresh_ecr_auth       'cmd-id-fake' 0
+out=$(run_script "$m" --skip-rollback)
+assert_contains "403 path logged" "$out" 'SSM-refreshing ECR auth'
+assert_calls_contain "SSM refresh called" "$m" 'ssm_refresh_ecr_auth i-0455a413e993ee78c'
+assert_calls_contain "resolve_tenant_instance_id called" "$m" 'resolve_tenant_instance_id chloe-dong'
+assert_calls_count "redeploy attempted twice (first + post-refresh)" "$m" '^cp_redeploy_tenant chloe-dong ' 2
+rm -rf "$m"
+
+printf '\n== Test 6: redeploy fail + --skip-rollback → exit 4 ==\n'
+m=$(mkmock)
+mock_set "$m" aws_ecr_get_image          '{"manifests":[]}' 0
+mock_set "$m" aws_ecr_describe_image     '' 1
+mock_set "$m" aws_ecr_put_image          '' 0
+mock_set "$m" cp_redeploy_tenant         '' 1   # generic failure (not 403)
+out=$(run_script "$m" --skip-rollback)
+assert_exit "redeploy fail + skip-rollback exits 4" "$out" 4
+assert_contains "logs redeploy failure" "$out" 'redeploy failed for chloe-dong'
+assert_contains "rollback skipped logged" "$out" 'rollback: skipped'
+assert_not_contains "no SSM refresh on non-403 failure" "$out" 'SSM-refreshing'
+rm -rf "$m"
+
+printf '\n== Test 7: redeploy fail + rollback succeeds → exit 3 ==\n'
+m=$(mkmock)
+mock_set "$m" aws_ecr_get_image          '{"manifests":[]}' 0
+mock_set "$m" aws_ecr_describe_image     '' 1
+mock_set "$m" aws_ecr_put_image          '' 0
+mock_set "$m" cp_redeploy_tenant         '' 1
+out=$(run_script "$m")
+assert_exit "redeploy fail with rollback exits 3" "$out" 3
+assert_contains "rollback fired" "$out" 'ROLLBACK:.*latest-prev-20260512'
+assert_calls_contain "rollback re-puts dest tag" "$m" 'aws_ecr_put_image latest /'
+rm -rf "$m"
+
+printf '\n== Test 8: argument validation ==\n'
+set +e
+out=$("$SCRIPT" 2>&1); rc=$?
+set -e
+if [[ $rc -eq 64 ]] && printf '%s' "$out" | grep -q 'required:.*--source-tag'; then
+  PASS=$((PASS + 1)); printf '  ✓ exit 64 on missing args with usage line\n'
+else
+  FAIL=$((FAIL + 1)); FAIL_NAMES+=("missing-args error")
+  printf '  ✗ exit 64 on missing args (got %s)\n' "$rc"
+fi
+
+set +e
+out=$("$SCRIPT" --source-tag x --dest-tag x --tenants y 2>&1); rc=$?
+set -e
+if [[ $rc -eq 64 ]] && printf '%s' "$out" | grep -q 'must differ'; then
+  PASS=$((PASS + 1)); printf '  ✓ exit 64 when source==dest\n'
+else
+  FAIL=$((FAIL + 1)); FAIL_NAMES+=("source==dest validation")
+  printf '  ✗ source==dest should fail (got %s)\n' "$rc"
+fi
+
+set +e
+out=$("$SCRIPT" --source-tag x --dest-tag y --tenants t --bogus-flag 2>&1); rc=$?
+set -e
+if [[ $rc -eq 64 ]] && printf '%s' "$out" | grep -q 'unknown argument'; then
+  PASS=$((PASS + 1)); printf '  ✓ exit 64 on unknown flag\n'
+else
+  FAIL=$((FAIL + 1)); FAIL_NAMES+=("unknown-flag error")
+  printf '  ✗ unknown-flag should fail (got %s)\n' "$rc"
+fi
+
+printf '\n== Test 9: ROLLBACK_TAG follows YYYYMMDD via NOW_OVERRIDE_DATE ==\n'
+m=$(mkmock)
+mock_set "$m" aws_ecr_get_image       '{}' 0
+mock_set "$m" aws_ecr_describe_image  '' 1
+mock_set "$m" aws_ecr_put_image       '' 0
+mock_set "$m" cp_redeploy_tenant      '{}' 0
+mock_set "$m" tenant_buildinfo        '{}' 0
+mock_set "$m" tenant_health           'ok' 0
+set +e
+NOW_OVERRIDE_DATE=20260603 SSM_SETTLE_SECONDS=0 "$SCRIPT" \
+  --source-tag a --dest-tag b --tenants t1 --mock-dir "$m" >/dev/null 2>&1
+rc=$?
+set -e
+if [[ $rc -eq 0 ]]; then
+  PASS=$((PASS + 1)); printf '  ✓ run succeeded with custom NOW_OVERRIDE_DATE\n'
+else
+  FAIL=$((FAIL + 1)); FAIL_NAMES+=("NOW_OVERRIDE_DATE run")
+  printf '  ✗ NOW_OVERRIDE_DATE run failed (rc=%s)\n' "$rc"
+fi
+assert_calls_contain "rollback tag uses NOW_OVERRIDE_DATE (20260603)" "$m" 'aws_ecr_put_image b-prev-20260603'
+rm -rf "$m"
+
+printf '\n== Test 10: empty source manifest fails preflight ==\n'
+m=$(mkmock)
+mock_set "$m" aws_ecr_get_image '' 0   # rc=0 but empty body (the "None" case)
+out=$(run_script "$m")
+assert_exit "empty source manifest fails preflight" "$out" 1
+assert_contains "empty manifest message" "$out" 'returned empty manifest'
+rm -rf "$m"
+
+printf '\n== Test 11: tenant_buildinfo failure during verify → rollback ==\n'
+m=$(mkmock)
+mock_set "$m" aws_ecr_get_image          '{"manifests":[]}' 0
+mock_set "$m" aws_ecr_describe_image     '' 1
+mock_set "$m" aws_ecr_put_image          '' 0
+mock_set "$m" cp_redeploy_tenant         '{"ok":true}' 0
+mock_set "$m" tenant_buildinfo           '' 1   # buildinfo probe fails
+mock_set "$m" tenant_health              'ok' 0
+out=$(run_script "$m")
+assert_exit "verify failure → rollback succeeds → exit 3" "$out" 3
+assert_contains "logs buildinfo failure" "$out" '/buildinfo failed for chloe-dong'
+assert_contains "rollback fired after verify fail" "$out" 'ROLLBACK:'
+rm -rf "$m"
+
+printf '\n== Test 12: ssm_refresh_ecr_auth JSON escaping (CWE-78 / OFFSEC-001) ==\n'
+# Verify the python3 snippet in ssm_refresh_ecr_auth produces valid JSON and
+# correctly escapes shell-injection characters in region + account ID fields.
+# The fix replaces unquoted shell-printf interpolation with json.dumps.
+PYCODE='import json,sys;r=sys.argv[1];a=sys.argv[2];ecr="aws ecr get-login-password --region "+json.dumps(r)[1:-1]+" | docker login --username AWS --password-stdin "+json.dumps(a)[1:-1]+".dkr.ecr."+json.dumps(r)[1:-1]+".amazonaws.com";print(json.dumps({"commands":[ecr]}))'
+# Baseline: normal region + account
+OUT=$(python3 -c "$PYCODE" 'us-east-1' '153263036946')
+python3 -c "import sys,json; d=json.loads(sys.stdin.read()); assert 'commands' in d; c=d['commands'][0]; assert 'us-east-1' in c and '153263036946' in c and c.startswith('aws ecr get-login-password')" <<< "$OUT" \
+  && echo "  ok: normal region+account" || { echo "  FAIL: invalid JSON for normal case"; exit 1; }
+# Injection: region with double-quote
+OUT=$(python3 -c "$PYCODE" 'us"-east-1' '153263036946')
+python3 -c "import sys,json; d=json.loads(sys.stdin.read()); c=d['commands'][0]; assert c" <<< "$OUT" \
+  && echo "  ok: region with quote injection → valid JSON" || { echo "  FAIL"; exit 1; }
+# Injection: account with double-quote
+OUT=$(python3 -c "$PYCODE" 'us-east-1' '15"326"3036946')
+python3 -c "import sys,json; d=json.loads(sys.stdin.read()); c=d['commands'][0]; assert c" <<< "$OUT" \
+  && echo "  ok: account with quote injection → valid JSON" || { echo "  FAIL"; exit 1; }
+# No double-encoding: region appears as literal 'us-east-1' in command string
+OUT=$(python3 -c "$PYCODE" 'us-east-1' '153263036946')
+python3 -c "import sys,json; d=json.loads(sys.stdin.read()); c=d['commands'][0]; assert 'us-east-1' in c" <<< "$OUT" \
+  && echo "  ok: no double-encoding in command string" || { echo "  FAIL"; exit 1; }
+# ─────────────────────────────────────────────────────────────────────────────
+
+printf '\n────────────────────────────────────\n'
+if [[ $FAIL -eq 0 ]]; then
+  printf 'All %d tests passed.\n' "$PASS"
+  exit 0
+else
+  printf '%d passed, %d failed.\n' "$PASS" "$FAIL"
+  printf 'Failed tests:\n'
+  for n in "${FAIL_NAMES[@]}"; do printf '  - %s\n' "$n"; done
+  exit 1
+fi