shepherd-onboard 0.1.10 → 0.1.12

package/README.md

@@ -10,8 +10,8 @@ Give this to a coding agent:
 npx -y shepherd-onboard@latest agent
 ```
 
-The command prints the exact prompt the agent should follow, then the exact follow-up commands to open Shepherd WorkOS login/signup, open source auth, open Granola's API key page, finalize, start cloud raw polling/backfills, and install local Messages sync.
-The agent prompt tells coding agents to ask short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. If Messages is selected, the agent runs `messages-chats --json`, shows the 20 most recent local Messages chats with contact/group names, and asks which chats to sync. Account creation/relinking always starts with Shepherd WorkOS auth.
+The command prints the exact prompt the agent should follow, then the exact follow-up commands to open Shepherd WorkOS login/signup, guide Google Workspace Admin Console delegation, open source auth for non-Google sources, open Granola's API key page, finalize, start cloud raw polling/backfills, and install local Messages sync.
+The agent prompt tells coding agents to ask short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. If Messages is selected, the agent runs `messages-chats`, opens a minimal local webpage with the 20 most recent local Messages chats, and has the user select which contacts/groups to sync. Account creation/relinking always starts with Shepherd WorkOS auth.
 Existing-organization joins are verified from Shepherd login and company email domain; the typed org name is not trusted by itself.
 
 ## Human Terminal One-liner
@@ -27,17 +27,33 @@ The command:
 - creates or reuses the Shepherd customer account from the WorkOS-authenticated email
 - creates or reuses the organization, including case-insensitive and close-name matches
 - only reuses an existing organization when the authenticated account is allowed to join it
-- opens Google Workspace authorization for Gmail, Drive, Docs, and Calendar consent
+- prints Google Workspace domain-wide delegation setup for a Workspace super admin
 - opens Slack authorization
 - opens the Granola desktop app to Settings -> Connectors -> API keys
 - collects the Granola API key after opening the Granola screen when Granola is enabled
-- shows the 20 most recent local Messages chats with contact/group names and only syncs the chats selected by the user
+- opens a minimal local webpage showing the 20 most recent local Messages chats with contact/group names and only syncs the chats selected by the user
 - sets up local macOS Messages raw sync with a background LaunchAgent scoped to the selected chats
 - starts raw polling/backfill for connected sources
 - does not start wiki generation, memory compilation, or doc summaries
 
 The command does not expose Railway, database, Redis, or internal service details to the user.
 
+## Google Workspace Domain-wide Delegation
+
+Business customers connect Google Workspace once as an admin. Employees do not create service accounts and do not each complete Google OAuth for Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, or Contacts.
+
+Customer-side setup in Google Admin Console:
+
+```text
+App name: Shepherd
+Service account email: gigabrain-delegation@shepherd-gigabrain.iam.gserviceaccount.com
+Domain-wide delegation OAuth Client ID: 118363960386741325727
+```
+
+The customer super admin authorizes that Client ID with the scopes printed by the CLI. The customer does not upload service account JSON; Shepherd stores its private service account JSON server-side in `GOOGLE_WORKSPACE_SERVICE_ACCOUNT_KEY_JSON` and requests delegated tokens with `sub=<allowed_employee_email>`.
+
+Shepherd must still enforce selected users and groups internally before impersonating or polling employee emails.
+
 ## Options
 
 ```sh
@@ -48,7 +64,7 @@ The command does not expose Railway, database, Redis, or internal service detail
 --messages-handle <value>  Messages phone number or Apple ID email
 --messages-chat-ids <ids>  Comma-separated chat IDs selected from messages-chats
 --messages-backfill-days   Local Messages backfill window, default 30
---no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar)
+--no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts)
 --no-slack                 Skip Slack
 --no-granola               Skip Granola
 --no-open-granola          Do not open the Granola API key screen
@@ -58,12 +74,14 @@ The command does not expose Railway, database, Redis, or internal service detail
 
 ## Messages Chat Selection
 
-List recent local Messages chats:
+Open the local Messages chat selector:
 
 ```sh
-npx -y shepherd-onboard@latest messages-chats --json
+npx -y shepherd-onboard@latest messages-chats
 ```
 
+Use `--json` for machine-readable chat metadata, or `--text` for a terminal list.
+
 Pass the selected chat IDs when finishing onboarding:
 
 ```sh

package/bin/shepherd-onboard.js

@@ -2,6 +2,7 @@
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import readline from "node:readline";
@@ -13,6 +14,7 @@ const DEFAULT_AGENT_STATE_PATH = join(homedir(), ".shepherd", "raw-onboarding-ag
 const MAX_BATCH_SIZE = 50;
 const MAX_QUEUE_MESSAGES = 10_000;
 const DEFAULT_RECENT_MESSAGE_CHATS = 20;
+const GRANOLA_API_KEYS_PATH = "/settings/integrations/api-keys";
 const GOOGLE_WORKSPACE_DELEGATION_APP_NAME = "Shepherd";
 const GOOGLE_WORKSPACE_DELEGATION_SERVICE_ACCOUNT_EMAIL =
   "gigabrain-delegation@shepherd-gigabrain.iam.gserviceaccount.com";
@@ -283,7 +285,9 @@ async function runAgentOnboarding() {
     account: session.account,
     sources,
     authUrls: session.authUrls ?? {},
-    googleWorkspaceDelegation: googleWorkspaceDelegationSetup(session.googleWorkspaceDelegation),
+    googleWorkspaceDelegation: sources.google
+      ? googleWorkspaceDelegationSetup(session.googleWorkspaceDelegation)
+      : undefined,
     workosAuth,
     createdAt: new Date().toISOString(),
   });
@@ -309,7 +313,7 @@ async function runAgentOnboarding() {
       googleWorkspaceDelegation: sources.google ? googleWorkspaceDelegationSetup(session.googleWorkspaceDelegation) : undefined,
       granolaApiKeyPage,
       statePath,
-      messagesChatsCommand: sources.messages ? `${agentCommand()} messages-chats --json` : undefined,
+      messagesChatsCommand: sources.messages ? `${agentCommand()} messages-chats` : undefined,
       nextCommand: `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"`,
       needsUserAction: agentNeedsUserAction(sources, opened),
     }, null, 2));
@@ -337,15 +341,16 @@ async function runAgentOnboarding() {
   }
   console.log(`State saved: ${statePath}`);
   console.log("\nCoding agent next steps:");
+  let step = 1;
   if (sources.google) {
-    console.log("1. Ask the user's Google Workspace super admin to authorize Shepherd in Google Admin Console with the Client ID and scopes above.");
+    console.log(`${step++}. Ask the user's Google Workspace super admin to authorize Shepherd in Google Admin Console with the Client ID and scopes above.`);
   }
-  if (sources.slack) console.log("2. Ask the user to finish the opened Slack browser authorization.");
-  if (sources.granola) console.log("3. Ask the user for their Granola API key from the Granola Mac app.");
+  if (sources.slack) console.log(`${step++}. Ask the user to finish the opened Slack browser authorization.`);
+  if (sources.granola) console.log(`${step++}. Ask the user for their Granola API key from the Granola Mac app.`);
   if (sources.messages) {
-    console.log(`4. Run ${agentCommand()} messages-chats --json, ask the user which recent chats to sync, and keep those chat IDs.`);
+    console.log(`${step++}. Run ${agentCommand()} messages-chats, have the user select chats in the browser page, and keep the printed chat IDs.`);
   }
-  console.log("5. Run:");
+  console.log(`${step++}. Run:`);
   console.log(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"`);
   console.log("   Omit either optional flag if that source is not being connected.");
 }
@@ -436,7 +441,7 @@ async function continueAgentOnboarding() {
   if (granolaApiKey) body.granolaApiKey = granolaApiKey;
   if (messagesHandle) body.imessage = { handle: messagesHandle };
   if (state.sources.messages && messagesHandle && selectedMessageChatIds.length === 0) {
-    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats --json, ask the user which chats to sync, then rerun --continue with --messages-chat-ids "<id1>,<id2>".`);
+    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats, have the user select chats in the browser page, then rerun --continue with --messages-chat-ids "<id1>,<id2>".`);
   }
 
   const finalized = await postJson(
@@ -518,6 +523,16 @@ async function runMessagesChatsCommand() {
     return;
   }
 
+  if (!args.text && !args.list) {
+    const selected = await selectChatsInBrowser(chats, { noOpen: Boolean(args["no-open"]) });
+    const selectedIds = selected.map((chat) => chat.chatId).join(",");
+    console.log(`\nSelected ${selected.length} Messages chat(s).`);
+    console.log(`messages-chat-ids=${selectedIds}`);
+    console.log("\nContinue with:");
+    console.log(`  ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "${selectedIds}"`);
+    return;
+  }
+
   console.log(`\nRecent local Messages chats (${chats.length})\n`);
   for (let i = 0; i < chats.length; i++) {
     console.log(`${String(i + 1).padStart(2, " ")}. ${formatMessageChatOption(chats[i])}`);
@@ -598,7 +613,7 @@ Usage:
   npx -y ${PACKAGE_NAME}@latest agent
   npx -y ${PACKAGE_NAME}@latest agent --login
   npx -y ${PACKAGE_NAME}@latest agent --name <name> --org <organization>
-  npx -y ${PACKAGE_NAME}@latest messages-chats --json
+  npx -y ${PACKAGE_NAME}@latest messages-chats
   npx -y ${PACKAGE_NAME}@latest agent --continue --granola-api-key <key> --messages-handle <value> --messages-chat-ids <ids>
   npx -y ${PACKAGE_NAME}@latest agent --status
   npx -y ${PACKAGE_NAME}@latest granola-api-keys
@@ -633,6 +648,8 @@ Usage:
 
 Options:
   --limit <n>                Number of recent chats to show. Defaults to ${DEFAULT_RECENT_MESSAGE_CHATS}.
+  --text                     Print a terminal list instead of opening the selector page.
+  --no-open                  Print the local selector URL instead of opening it.
   --json                     Print machine-readable chat IDs and labels.
   --help                     Show this help.
 `);
@@ -735,7 +752,7 @@ function printAgentContract() {
       "--granola-api-key \"<granola_key>\" if Granola is being connected",
     ],
     statusCommand: `${command} agent --status`,
-    messagesChatsCommand: `${command} messages-chats --json`,
+    messagesChatsCommand: `${command} messages-chats`,
     googleWorkspaceDelegation: googleWorkspaceDelegationSetup(),
     orgSecurity: "Existing organizations are only reused when Shepherd can verify the authenticated user belongs there, for example by an existing Shepherd account/membership or matching non-personal company email domain. Similar spelling helps match verified orgs, but cannot attach an unverified user to someone else's org.",
     expectedResult: "Cloud sources start raw polling/backfill in the customer-facing Shepherd environment. Local Messages starts via a macOS LaunchAgent when run on macOS. Downstream wiki, memory, and summary compilers remain outside this onboarding flow.",
@@ -758,7 +775,7 @@ Ask with short interactive prompts, not as one pasted checklist.
 
 Start with selection questions to determine intent:
 1. Organization: Join existing org, or Create new org.
-2. Sources: Google Workspace (Gmail/Drive/Docs/Calendar), Slack, Granola, Messages. Allow multi-select if your interface supports it.
+2. Sources: Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts), Slack, Granola, Messages. Allow multi-select if your interface supports it.
 3. Messages, if selected: Skip Messages, or Provide handle.
 
 When discussing existing orgs, keep it short: Shepherd verifies the join from their Shepherd login and company email domain. The org name they type is not trusted by itself.
@@ -767,6 +784,7 @@ Before source setup, always run:
   ${payload.loginCommand}
 
 That opens one WorkOS Shepherd login/signup flow and saves a local onboarding auth session. It creates or relinks the Shepherd customer account; the next setup command attaches sources to the same production cloud account rows.
+Do not use WorkOS Auth, WorkOS Pipes, or per-user Google OAuth for Google Workspace. WorkOS login is only Shepherd account identity.
 
 Ask the user for:
 1. Full name
@@ -780,7 +798,7 @@ If they are joining an existing org, ask for the org name they believe they belo
 If Messages is selected, run:
   ${payload.messagesChatsCommand}
 
-Show the 20 recent local Messages chats to the user as a selection question. Include both DMs and groups, and use the displayed contact/group names. Ask which chats Shepherd should sync. Do not select all chats by default.
+This opens a minimal local webpage with the 20 recent local Messages chats. Have the user select which contacts/groups Shepherd should sync. Do not select all chats by default. When the command returns, keep the printed comma-separated chat IDs.
 
 Then run:
   ${payload.startCommand}
@@ -791,8 +809,21 @@ Add skip flags for sources the user did not select:
 - --no-granola
 - --no-messages
 
-That command creates/reuses the customer user and org, opens Google Workspace/Slack browser auth, and saves local state.
-If your browser automation can complete those auth screens, do it. If it cannot click through OAuth screens, leave the opened browser tabs for the user and ask them to complete Google Workspace and Slack auth.
+That command creates/reuses the customer user and org, prints Google Workspace domain-wide delegation setup values, opens Slack browser auth if selected, and saves local state.
+
+If Google Workspace is selected, show this Admin Console setup to the user and have their Google Workspace super admin authorize it:
+
+App name: ${payload.googleWorkspaceDelegation.appName}
+Service account email: ${payload.googleWorkspaceDelegation.serviceAccountEmail}
+Domain-wide delegation OAuth Client ID: ${payload.googleWorkspaceDelegation.clientId}
+
+Scopes:
+${payload.googleWorkspaceDelegation.scopes.join("\n")}
+
+The customer does not create a service account and does not upload service account JSON in the default Shepherd-managed flow. Their super admin only authorizes the Client ID and scopes in Google Admin Console. Shepherd's backend stores and uses its private service account JSON server-side.
+Shepherd must still enforce selected users and groups internally before polling or impersonating any employee email.
+
+If Slack is selected and your browser automation can complete that auth screen, do it. If it cannot click through OAuth screens, leave the opened browser tab for the user and ask them to complete Slack auth.
 
 If Granola is selected, it also opens the Granola desktop app. If your local app automation can navigate it, go to:
   Settings -> Connectors -> API keys
@@ -802,7 +833,7 @@ If Granola did not come forward, run:
   ${payload.granolaApiKeyCommand}
 That command opens Granola and tries to navigate to Settings -> Connectors -> API keys. If your tool cannot click inside Granola, leave Granola open and ask the user to go to that screen.
 
-After Google Workspace and Slack browser auth is complete, and after the user has copied a Granola API key from the opened Granola screen if they want Granola, run:
+After Google Workspace Admin Console delegation and Slack browser auth are complete, and after the user has copied a Granola API key from the opened Granola screen if they want Granola, run:
   ${payload.continueCommand} --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"
 
 Omit either optional flag if that source is not being connected.
@@ -905,7 +936,7 @@ function agentNeedsUserAction(sources, opened) {
   if (sources.google) actions.push("Have the customer's Google Workspace super admin authorize Shepherd's domain-wide delegation Client ID and scopes in Google Admin Console.");
   if (sources.slack && opened.includes("slack")) actions.push("Complete Slack browser authorization.");
   if (sources.granola) actions.push("Create/copy a Granola API key from the Granola Mac app.");
-  if (sources.messages) actions.push("Run messages-chats, ask the user which recent local Messages chats to sync, then pass the selected chat IDs with the Messages handle.");
+  if (sources.messages) actions.push("Run messages-chats, have the user select local Messages contacts/groups in the browser, then pass the printed chat IDs with the Messages handle.");
   return actions;
 }
 
@@ -1017,7 +1048,7 @@ async function openOrPrint(url, opts) {
 }
 
 async function openGranolaApiKeys(opts = {}) {
-  const deepLink = "granola://settings/integrations";
+  const deepLink = granolaApiKeysDeepLink();
   if (opts.noOpen) {
     console.log("Granola API keys: open the Granola desktop app -> Settings -> Connectors -> API keys");
     return { opened: false, target: "Granola Settings -> Connectors -> API keys" };
@@ -1030,19 +1061,20 @@ async function openGranolaApiKeys(opts = {}) {
 
   console.log("\nOpening Granola API keys");
   const bundleResult = await execFileQuiet("open", ["-b", "com.granola.app"], { ignoreError: true, captureError: true });
-  await sleep(500);
-  await execFileQuiet("open", [deepLink], { ignoreError: true, captureError: true });
-  await sleep(500);
+  await sleep(900);
+  const deepLinkResult = await execFileQuiet("open", ["-u", deepLink], { ignoreError: true, captureError: true });
+  await sleep(700);
+  const deepLinkRetryResult = await execFileQuiet("open", ["-u", deepLink], { ignoreError: true, captureError: true });
+  await sleep(300);
   const activateByBundleResult = await execFileQuiet("osascript", [
     "-e",
     'tell application id "com.granola.app" to activate',
   ], { ignoreError: true, captureError: true });
   const activateByNameResult = await execFileQuiet("open", ["-a", "Granola"], { ignoreError: true, captureError: true });
 
-  if (bundleResult.error && activateByBundleResult.error && activateByNameResult.error) {
+  if (bundleResult.error && deepLinkResult.error && deepLinkRetryResult.error && activateByBundleResult.error && activateByNameResult.error) {
     await execFileQuiet("open", ["-a", "Granola"], { ignoreError: true });
   }
-  await navigateGranolaApiKeysWithAppleScript();
 
   return {
     opened: true,
@@ -1052,32 +1084,8 @@ async function openGranolaApiKeys(opts = {}) {
   };
 }
 
-async function navigateGranolaApiKeysWithAppleScript() {
-  const script = `
-tell application id "com.granola.app" to activate
-delay 0.7
-tell application "System Events"
-  if not (exists process "Granola") then return
-  tell process "Granola"
-    set frontmost to true
-    try
-      set {x, y} to position of window 1
-      set {w, h} to size of window 1
-      click at {x + w - 55, y + 810}
-      return
-    end try
-    try
-      keystroke "," using command down
-      delay 0.5
-      set {x, y} to position of window 1
-      set {w, h} to size of window 1
-      click at {x + w - 55, y + 810}
-      return
-    end try
-  end tell
-end tell
-`;
-  await execFileQuiet("osascript", ["-e", script], { ignoreError: true });
+function granolaApiKeysDeepLink() {
+  return `granola://open?path=${encodeURIComponent(GRANOLA_API_KEYS_PATH)}`;
 }
 
 async function postJson(url, body, opts = {}) {
@@ -1196,7 +1204,7 @@ async function selectRecentMessageChats() {
   }
 
   if (!process.stdin.isTTY) {
-    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats --json and pass --messages-chat-ids "<id1>,<id2>".`);
+    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats and pass --messages-chat-ids "<id1>,<id2>".`);
   }
 
   const chats = await listRecentMessageChats({ limit: DEFAULT_RECENT_MESSAGE_CHATS });
@@ -1204,6 +1212,10 @@ async function selectRecentMessageChats() {
     throw new Error("No recent local Messages chats were found on this Mac.");
   }
 
+  if (!args.text && !args.list) {
+    return selectChatsInBrowser(chats, { noOpen: Boolean(args["no-open"]) });
+  }
+
   console.log(`\nSelect local Messages chats to sync\n`);
   console.log("Shepherd will only pull from the chats you select.");
   for (let i = 0; i < chats.length; i++) {
@@ -1216,6 +1228,356 @@ async function selectRecentMessageChats() {
   return indexes.map((idx) => chats[idx]);
 }
 
+async function selectChatsInBrowser(chats, opts = {}) {
+  if (!chats.length) throw new Error("No recent local Messages chats were found on this Mac.");
+
+  const token = Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2);
+  let settled = false;
+  let server;
+
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      server?.close();
+      reject(new Error("Messages chat selection timed out."));
+    }, 20 * 60 * 1000);
+
+    server = createServer(async (req, res) => {
+      try {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "127.0.0.1"}`);
+
+        if (req.method === "GET" && url.pathname === "/") {
+          sendHtml(res, renderMessagesSelectorPage(chats, token));
+          return;
+        }
+
+        if (req.method === "POST" && url.pathname === "/select") {
+          const body = await readRequestBody(req);
+          const form = new URLSearchParams(body);
+          if (form.get("token") !== token) {
+            sendHtml(res, renderMessagesDonePage("Invalid selection session.", true), 403);
+            return;
+          }
+          const selectedIds = form.getAll("chatId").filter(Boolean);
+          const selectedSet = new Set(selectedIds);
+          const selected = chats.filter((chat) => selectedSet.has(chat.chatId));
+          if (selected.length === 0) {
+            sendHtml(res, renderMessagesSelectorPage(chats, token, "Select at least one chat."));
+            return;
+          }
+
+          sendHtml(res, renderMessagesDonePage(`${selected.length} chat${selected.length === 1 ? "" : "s"} selected.`));
+          if (!settled) {
+            settled = true;
+            clearTimeout(timeout);
+            setTimeout(() => server.close(), 100);
+            resolve(selected);
+          }
+          return;
+        }
+
+        sendHtml(res, renderMessagesDonePage("Not found.", true), 404);
+      } catch (err) {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timeout);
+          server?.close();
+          reject(err);
+        }
+      }
+    });
+
+    server.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(err);
+    });
+
+    server.listen(0, "127.0.0.1", async () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : null;
+      if (!port) {
+        settled = true;
+        clearTimeout(timeout);
+        server.close();
+        reject(new Error("Could not start local Messages selector."));
+        return;
+      }
+      const url = `http://127.0.0.1:${port}/`;
+      console.log(`\nOpening Messages chat selector: ${url}`);
+      await openOrPrint(url, { noOpen: Boolean(opts.noOpen) });
+      console.log("Select the Messages chats to sync in the browser.");
+    });
+  });
+}
+
+function renderMessagesSelectorPage(chats, token, error = "") {
+  const rows = chats.map((chat) => `
+      <label class="chat-row">
+        <input type="checkbox" name="chatId" value="${htmlAttr(chat.chatId)}">
+        <span class="box" aria-hidden="true"></span>
+        <span class="chat-main">
+          <span class="chat-top">
+            <span class="chat-name">${html(chat.label)}</span>
+            <span class="chat-kind">${html(chat.kind === "group" ? "Group" : chat.kind === "dm" ? "Contact" : "Chat")}</span>
+          </span>
+          ${renderChatPeople(chat)}
+          <span class="chat-meta">${html(formatMessageChatMeta(chat))}</span>
+        </span>
+      </label>`).join("");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Select Messages Chats</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --bg: #FCFCFC;
+      --fg: #111111;
+      --muted: #6D726D;
+      --line: #E8ECE8;
+      --panel: #FFFFFF;
+      --button: #136033;
+      --button-text: #FFFFFF;
+      --link: #136033;
+      --radius: 10px;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #000000;
+        --fg: #F8F8F8;
+        --muted: #A2A8A2;
+        --line: #202520;
+        --panel: #070907;
+        --button: #FFFFFF;
+        --button-text: #000000;
+        --link: #136033;
+      }
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--fg);
+      font-family: Geist, "Geist Sans", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      letter-spacing: 0;
+    }
+    main {
+      width: min(760px, calc(100vw - 32px));
+      margin: 40px auto;
+    }
+    header {
+      display: flex;
+      justify-content: space-between;
+      gap: 16px;
+      align-items: end;
+      padding-bottom: 18px;
+      border-bottom: 1px solid var(--line);
+    }
+    h1 {
+      margin: 0;
+      font-size: 24px;
+      line-height: 1.1;
+      font-weight: 650;
+    }
+    .count {
+      color: var(--muted);
+      font-size: 13px;
+      white-space: nowrap;
+    }
+    form {
+      margin-top: 18px;
+    }
+    .error {
+      margin: 0 0 12px;
+      color: #9B1C1C;
+      font-size: 14px;
+    }
+    .chat-list {
+      display: grid;
+      gap: 8px;
+      margin: 0 0 18px;
+    }
+    .chat-row {
+      display: grid;
+      grid-template-columns: 24px 1fr;
+      gap: 12px;
+      align-items: start;
+      padding: 13px 14px;
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: var(--radius);
+      cursor: pointer;
+    }
+    .chat-row:hover {
+      border-color: color-mix(in srgb, var(--link) 45%, var(--line));
+    }
+    input[type="checkbox"] {
+      position: absolute;
+      opacity: 0;
+      pointer-events: none;
+    }
+    .box {
+      width: 18px;
+      height: 18px;
+      margin-top: 2px;
+      border: 1.5px solid var(--muted);
+      border-radius: 5px;
+      display: inline-grid;
+      place-items: center;
+    }
+    input[type="checkbox"]:checked + .box {
+      background: var(--button);
+      border-color: var(--button);
+    }
+    input[type="checkbox"]:checked + .box::after {
+      content: "";
+      width: 7px;
+      height: 4px;
+      border-left: 2px solid var(--button-text);
+      border-bottom: 2px solid var(--button-text);
+      transform: rotate(-45deg) translateY(-1px);
+    }
+    .chat-main {
+      min-width: 0;
+      display: grid;
+      gap: 4px;
+    }
+    .chat-top {
+      display: flex;
+      gap: 10px;
+      align-items: center;
+      min-width: 0;
+    }
+    .chat-name {
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      font-size: 15px;
+      font-weight: 600;
+    }
+    .chat-kind {
+      color: var(--link);
+      font-size: 12px;
+      flex: none;
+    }
+    .chat-people,
+    .chat-meta {
+      color: var(--muted);
+      font-size: 13px;
+      line-height: 1.35;
+      overflow-wrap: anywhere;
+    }
+    .actions {
+      display: flex;
+      justify-content: flex-end;
+      position: sticky;
+      bottom: 0;
+      padding: 14px 0 0;
+      background: linear-gradient(to top, var(--bg) 70%, transparent);
+    }
+    button {
+      appearance: none;
+      border: 0;
+      border-radius: var(--radius);
+      background: var(--button);
+      color: var(--button-text);
+      padding: 10px 14px;
+      font: inherit;
+      font-weight: 620;
+      cursor: pointer;
+    }
+    a { color: var(--link); }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <h1>Select Messages chats</h1>
+      <div class="count">${chats.length} recent chats</div>
+    </header>
+    <form method="post" action="/select">
+      <input type="hidden" name="token" value="${htmlAttr(token)}">
+      ${error ? `<p class="error">${html(error)}</p>` : ""}
+      <div class="chat-list">${rows}</div>
+      <div class="actions">
+        <button type="submit">Use selected chats</button>
+      </div>
+    </form>
+  </main>
+</body>
+</html>`;
+}
+
+function renderMessagesDonePage(message, isError = false) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Messages Selection</title>
+  <style>
+    :root { color-scheme: light dark; --bg: #FCFCFC; --fg: #111; --muted: #6D726D; --button: #136033; --button-text: #FFFFFF; --radius: 10px; }
+    @media (prefers-color-scheme: dark) { :root { --bg: #000; --fg: #F8F8F8; --muted: #A2A8A2; --button: #FFFFFF; --button-text: #000; } }
+    body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: var(--bg); color: var(--fg); font-family: Geist, "Geist Sans", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; letter-spacing: 0; }
+    main { width: min(420px, calc(100vw - 32px)); }
+    h1 { margin: 0 0 8px; font-size: 24px; line-height: 1.1; font-weight: 650; }
+    p { margin: 0; color: var(--muted); font-size: 14px; line-height: 1.45; }
+    .mark { width: 34px; height: 34px; border-radius: var(--radius); display: grid; place-items: center; margin-bottom: 14px; background: var(--button); color: var(--button-text); font-weight: 700; }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="mark">${isError ? "!" : "OK"}</div>
+    <h1>${html(message)}</h1>
+    <p>${isError ? "Return to the terminal and retry." : "You can close this tab and return to the terminal."}</p>
+  </main>
+</body>
+</html>`;
+}
+
+function renderChatPeople(chat) {
+  const names = chat.participants?.map((participant) => participant.name ?? participant.handle).filter(Boolean) ?? [];
+  if (!names.length) return "";
+  return `<span class="chat-people">${html(names.slice(0, 6).join(", "))}</span>`;
+}
+
+function formatMessageChatMeta(chat) {
+  const parts = [];
+  if (chat.service) parts.push(chat.service);
+  if (chat.lastMessageAt) parts.push(new Date(chat.lastMessageAt).toLocaleString());
+  return parts.join(" · ");
+}
+
+function sendHtml(res, body, status = 200) {
+  res.writeHead(status, {
+    "Content-Type": "text/html; charset=utf-8",
+    "Cache-Control": "no-store",
+  });
+  res.end(body);
+}
+
+function readRequestBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+      body += chunk;
+      if (body.length > 64_000) {
+        reject(new Error("Request body too large."));
+        req.destroy();
+      }
+    });
+    req.on("end", () => resolve(body));
+    req.on("error", reject);
+  });
+}
+
 async function listRecentMessageChats({ limit }) {
   if (platform() !== "darwin") {
     throw new Error("local Messages chat discovery is only supported on macOS");
@@ -1680,6 +2042,17 @@ function parseAllowedChatIds(value) {
   return [...new Set(raw.map((chatId) => String(chatId).trim()).filter(Boolean))];
 }
 
+function html(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function htmlAttr(value) {
+  return html(value).replace(/"/g, "&quot;");
+}
+
 class MessagesBatchSender {
   constructor(apiUrl, agentToken, userId) {
     this.apiUrl = trimTrailingSlash(apiUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shepherd-onboard",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Customer-facing Shepherd raw sync onboarding CLI",
   "type": "module",
   "bin": {