askshepherd 0.1.44 → 0.1.45

package/bin/shepherd-onboard.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { execFile, execFileSync, spawn } from "node:child_process";
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID } from "node:crypto";
 import { constants as fsConstants, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, watch, writeFileSync } from "node:fs";
 import { access, chmod, mkdir, mkdtemp, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
@@ -37,7 +37,7 @@ const MCP_ENVIRONMENT_TARGETS = {
 const DEFAULT_API_URL = CUSTOMER_DEPLOY_API_URL;
 const PACKAGE_NAME = "askshepherd";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
-const PACKAGE_VERSION = "0.1.44";
+const PACKAGE_VERSION = "0.1.45";
 const DEFAULT_OFFICE_AUDIO_TRANSCRIPTION_BACKEND = "pyannote_full";
 const OFFICE_AUDIO_TRANSCRIPTION_BACKENDS = new Set([
   "pyannote_full",
@@ -341,6 +341,16 @@ async function runOnboarding() {
   const finalizeBody = { sessionToken: session.sessionToken };
   let selectedMessageChats = [];
 
+  if (sources.github) {
+    console.log("\nGitHub repository sync");
+    const githubToken = await valueOrPrompt("github-token", "GitHub fine-grained or classic PAT with repository webhook/API access", { secret: true, optional: true });
+    const githubRepoFullName = await valueOrPrompt("github-repo", "GitHub repository owner/name", { optional: true });
+    if (githubToken || githubRepoFullName) {
+      finalizeBody.githubToken = githubToken;
+      finalizeBody.githubRepoFullName = githubRepoFullName;
+    }
+  }
+
   if (sources.granola) {
     if (session.authUrls?.granola) {
       console.log("\nGranola authorization");
@@ -537,7 +547,7 @@ async function runAgentOnboarding() {
       currentAction,
       statePath,
       messagesChatsCommand: sources.messages ? `${agentCommand()} messages-chats` : undefined,
-      nextCommand: `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id[,apple_id]>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<legacy_granola_key>"`,
+      nextCommand: `${agentCommand()} agent --continue --github-token "<github_pat>" --github-repo "<owner/repo>" --messages-handle "<phone_or_apple_id[,apple_id]>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<legacy_granola_key>"`,
       needsUserAction: agentNeedsUserAction(sources, currentAction),
     }, null, 2));
     return;
@@ -556,7 +566,7 @@ async function runAgentOnboarding() {
   });
 
   console.log("\nAfter that modality is complete, run:");
-  console.log(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id[,apple_id]>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<legacy_granola_key>"`);
+  console.log(`   ${agentCommand()} agent --continue --github-token "<github_pat>" --github-repo "<owner/repo>" --messages-handle "<phone_or_apple_id[,apple_id]>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<legacy_granola_key>"`);
   console.log("   Omit either optional flag if that source is not being connected.");
 }
 
@@ -1196,6 +1206,20 @@ function localMcpTools(opts = {}) {
   };
 
   const tools = [
+    {
+      name: "shepherd_onboarding_guide",
+      description: "LOCAL agent-facing Shepherd onboarding workflow. Use when setting up Shepherd, choosing sources, deciding usage-skill/MCP install targets, or recovering the next onboarding step.",
+      inputSchema: emptyInputSchema,
+      annotations: readOnlyAnnotations,
+      _meta: { provider: "local_npm", command: `${agentCommand()} guide` },
+    },
+    {
+      name: "shepherd_troubleshoot",
+      description: "LOCAL state-aware Shepherd onboarding/setup help. Use when confused, blocked, auth expired, source setup is pending, local sync is unhealthy, or the wiki is still building.",
+      inputSchema: emptyInputSchema,
+      annotations: readOnlyAnnotations,
+      _meta: { provider: "local_npm", command: `${agentCommand()} troubleshoot` },
+    },
     {
       name: "shepherd_status",
       description: "LOCAL Shepherd setup and sync status. Use this first when the user asks what they have enabled, what is connected, whether Shepherd is syncing, or why local Messages/Coding Sessions are not running. This is backed by the local Shepherd CLI; do not use production memory/wiki tools or shell/file exploration for local setup status.",
@@ -1274,7 +1298,7 @@ function localMcpInstructions(remoteInstructions, remoteConnectError, opts = {})
   const environmentLabel = opts.environment ? mcpEnvironmentLabel(opts.environment, opts.mcpUrl) : "saved Shepherd MCP endpoint";
   return [
     "This MCP server is the local Shepherd CLI wrapper plus deployed Shepherd memory/wiki tools.",
-    `For local setup/sync questions like "what do I have set up on Shepherd", "what have I enabled", "is Shepherd syncing", "help me set up coding agent sessions", "enable coding sessions", or "enable coding agent sessions locally for Shepherd", use shepherd_status, shepherd_setup_coding_sessions, or shepherd_enable_coding_sessions first. These local tools route to the local Shepherd CLI status/setup flow. The Shepherd CLI is the only component that may perform bounded local checks of Shepherd state, LaunchAgents, and known Codex/Claude session locations.`,
+    `For agent-led onboarding, source choice, usage-skill install targets, MCP install targets, or "what step is next", use shepherd_onboarding_guide first. If setup is blocked or confusing, use shepherd_troubleshoot. For local setup/sync questions like "what do I have set up on Shepherd", "what have I enabled", "is Shepherd syncing", "help me set up coding agent sessions", "enable coding sessions", or "enable coding agent sessions locally for Shepherd", use shepherd_status, shepherd_setup_coding_sessions, or shepherd_enable_coding_sessions first. These local tools route to the local Shepherd CLI status/setup flow. The Shepherd CLI is the only component that may perform bounded local checks of Shepherd state, LaunchAgents, and known Codex/Claude session locations.`,
     "Hard boundary: do not use shell or filesystem tools such as ls, find, rg, grep, cat, Read, Glob, or Explore to inspect the user's home directory, repositories, ~/.codex, ~/.claude, or ~/.shepherd for Shepherd setup. If local status is needed, call shepherd_status or run the exact Shepherd CLI status command.",
     `If the user asks for raw local status outside MCP, tell them to run ${agentCommand()} status. For setup of coding agent sessions, ask consent, then use ${agentCommand()} login if needed, ${agentCommand()} onboard --add-sources coding-sessions --name "<full_name>" --org "<organization>", ${agentCommand()} continue, then ${agentCommand()} status.`,
     "For memory/wiki questions when readiness is uncertain, call shepherd_wiki_status first. If it or any deployed Shepherd tool returns status: \"wiki_not_ready\", do not answer the underlying memory/wiki question yet; report the readiness progress/ETA and ask the user to retry when the initial build is ready.",
@@ -1289,6 +1313,16 @@ function localMcpInstructions(remoteInstructions, remoteConnectError, opts = {})
 }
 
 async function callLocalMcpTool(name, context = {}) {
+  if (name === "shepherd_onboarding_guide") {
+    const status = await collectShepherdStatus();
+    return localMcpTextResult(renderOnboardingGuideMcpResult(status));
+  }
+
+  if (name === "shepherd_troubleshoot") {
+    const status = await collectShepherdStatus();
+    return localMcpTextResult(renderTroubleshootMcpResult(status));
+  }
+
   if (name === "shepherd_status" || name === "shepherd_local_status") {
     const status = await collectShepherdStatus();
     return localMcpTextResult([
@@ -1393,6 +1427,99 @@ function renderCodingSessionsSetupMcpResult(status) {
   ].join("\n");
 }
 
+function renderOnboardingGuideMcpResult(status) {
+  return [
+    "Shepherd onboarding workflow",
+    "",
+    "Use the wrapper workflow as the source of truth for agent-led onboarding:",
+    `  ${agentCommand()} guide`,
+    "",
+    "High-level flow:",
+    "1. Ask where to install the Shepherd usage skill: Codex, Claude Code, both, or skip.",
+    `   Command: ${agentCommand()} skill --install <codex|claude|all>`,
+    "2. Ask source choices with a native multi-select UI/control when available.",
+    "   Offer only sources the guide says are available. Ask explicit consent before Messages or Coding Sessions.",
+    `3. Authenticate the Shepherd account with WorkOS: ${agentCommand()} login`,
+    `4. Start onboarding with confirmed full name, org, and selected sources: ${agentCommand()} onboard --name "<full_name>" --org "<organization>" --sources "<sources>"`,
+    `5. After each browser/admin/PAT/local permission step, run: ${agentCommand()} continue`,
+    `6. Verify local setup and readiness: ${agentCommand()} status, ${agentCommand()} shepherd_wiki_status, ${agentCommand()} tools --json`,
+    `7. Ask where to install Shepherd MCP for querying: ${agentCommand()} mcp-login --install <codex|claude|all>`,
+    "",
+    "Messages guardrails: require explicit consent, Full Disk Access, and selected chats from messages-chats; never sync all chats by default.",
+    "Coding Sessions guardrails: require explicit consent; Shepherd syncs bounded redacted Codex/Claude Code session metadata, not raw logs.",
+    "Wiki readiness guardrail: if shepherd_wiki_status returns wiki_not_ready, say Shepherd is still learning and include progress/ETA instead of answering the memory question.",
+    "",
+    "Current local status:",
+    renderShepherdStatus(status),
+  ].join("\n");
+}
+
+function renderTroubleshootMcpResult(status) {
+  const diagnostics = [];
+  if (!status.configured || !status.account) {
+    diagnostics.push([
+      "No saved Shepherd onboarding session.",
+      `Run ${agentCommand()} login, then ${agentCommand()} guide.`,
+    ]);
+  }
+  if (status.productionError) {
+    diagnostics.push([
+      `Backend status is unavailable: ${status.productionError}`,
+      `Run ${agentCommand()} login, then ${agentCommand()} continue.`,
+    ]);
+  }
+  for (const source of statusSourceRows(status.providers, status.savedSources).filter((row) => row.selected && !row.connected)) {
+    diagnostics.push([
+      `${source.label} is selected but not connected.`,
+      `Run ${agentCommand()} continue and complete the current modality it prints.`,
+    ]);
+  }
+  if (status.local.messages.configPath && status.local.messages.storage?.readable === false) {
+    diagnostics.push([
+      "Messages database is not readable.",
+      `Grant Full Disk Access to the onboarding app and Node.js, then run ${agentCommand()} messages-chats.`,
+    ]);
+  }
+  if (status.local.messages.configPath && status.local.messages.launch?.running === false) {
+    diagnostics.push([
+      "Messages LaunchAgent is installed but not running.",
+      `Run ${agentCommand()} status after fixing Full Disk Access; rerun continue if status asks for it.`,
+    ]);
+  }
+  if (status.local.codingSessions.configPath && status.local.codingSessions.launch?.running === false) {
+    diagnostics.push([
+      "Coding Sessions LaunchAgent is installed but not running.",
+      `Run ${agentCommand()} coding-sessions-status, then ${agentCommand()} continue if status asks for setup repair.`,
+    ]);
+  }
+  const readiness = wikiReadinessPayloadFromStatus(status);
+  if (readiness.status === "wiki_not_ready") {
+    diagnostics.push([
+      "Wiki is still building.",
+      "This is not a setup failure. Tell the user Shepherd is still learning and include progress/ETA from shepherd_wiki_status.",
+    ]);
+  }
+  if (diagnostics.length === 0) {
+    diagnostics.push([
+      "No obvious local onboarding blocker found.",
+      `Run ${agentCommand()} tools --json and use exact listed tool names.`,
+    ]);
+  }
+  return [
+    "Shepherd troubleshooting",
+    "",
+    ...diagnostics.flatMap(([symptom, fix], index) => [
+      `${index + 1}. ${symptom}`,
+      `   Fix: ${fix}`,
+    ]),
+    "",
+    "Current local status:",
+    renderShepherdStatus(status),
+    "",
+    `Full workflow: ${agentCommand()} guide`,
+  ].join("\n");
+}
+
 function localMcpTextResult(text, isError = false) {
   return {
     content: [{ type: "text", text }],
@@ -1546,10 +1673,14 @@ function printMcpInstallResults(results) {
 async function continueAgentOnboarding() {
   let state = await readAgentState();
   const body = { sessionToken: state.sessionToken };
+  const githubToken = stringArg("github-token");
+  const githubRepoFullName = stringArg("github-repo");
   const granolaApiKey = stringArg("granola-api-key");
   const messagesHandles = parseMessageHandleList(stringArg("messages-handle"));
   const messagesHandle = messagesHandles[0] ?? null;
   const selectedMessageChatIds = parseMessageChatIdsArg();
+  if (githubToken) body.githubToken = githubToken;
+  if (githubRepoFullName) body.githubRepoFullName = githubRepoFullName;
   if (granolaApiKey) body.granolaApiKey = granolaApiKey;
   if (messagesHandle) body.imessage = { handle: messagesHandle, handles: messagesHandles };
   if (state.sources.messages && messagesHandle && selectedMessageChatIds.length === 0) {
@@ -1636,7 +1767,7 @@ async function continueAgentOnboarding() {
       processing: finalized.processing,
       errors: errors ? safeErrorRecord(errors) : undefined,
       currentAction,
-      nextCommand: errors ? `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id[,apple_id]>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<legacy_granola_key>"` : undefined,
+      nextCommand: errors ? `${agentCommand()} agent --continue --github-token "<github_pat>" --github-repo "<owner/repo>" --messages-handle "<phone_or_apple_id[,apple_id]>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<legacy_granola_key>"` : undefined,
       mcpInstall: errors ? undefined : {
         prompt: "Ask where to install Shepherd MCP for this customer: Codex, Claude Code, both, or none.",
         targets: MCP_INSTALL_TARGETS,
@@ -1657,7 +1788,7 @@ async function continueAgentOnboarding() {
     });
 
     console.log("\nAfter that modality is complete, rerun:");
-    console.log(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id[,apple_id]>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<legacy_granola_key>"`);
+    console.log(`   ${agentCommand()} agent --continue --github-token "<github_pat>" --github-repo "<owner/repo>" --messages-handle "<phone_or_apple_id[,apple_id]>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<legacy_granola_key>"`);
     console.log("   Omit either optional flag if that source is not being connected.");
     return;
   }
@@ -1863,7 +1994,18 @@ function renderLocalCodingSessionsStatus(status) {
     lines.push(`  ${probe.provider}: ${probe.path} ${probe.readable ? "readable" : `not readable (${probe.reason})`}`);
   }
   if (status.lastSync) {
-    lines.push(`  Last sync: ${status.lastSync.finishedAt ?? "unknown"} (${status.lastSync.scanned ?? 0} scanned, ${status.lastSync.changed ?? 0} changed)`);
+    const uploadable = status.lastSync.uploadable ?? status.lastSync.scanned ?? 0;
+    const ignored = status.lastSync.filesIgnored ?? null;
+    const ignoredText = ignored == null ? "" : `, ${ignored} ignored`;
+    lines.push(`  Last sync: ${status.lastSync.finishedAt ?? "unknown"} (${uploadable} uploadable, ${status.lastSync.changed ?? 0} changed${ignoredText})`);
+    const providerStatus = status.lastSync.providerStatus && typeof status.lastSync.providerStatus === "object" && !Array.isArray(status.lastSync.providerStatus)
+      ? status.lastSync.providerStatus
+      : {};
+    for (const provider of ["codex", "claude"]) {
+      const info = providerStatus[provider];
+      if (!info || typeof info !== "object" || Array.isArray(info)) continue;
+      lines.push(`    ${provider}: ${info.uploadable ?? info.scanned ?? 0} uploadable${info.filesIgnored == null ? "" : `, ${info.filesIgnored} ignored`}`);
+    }
   } else {
     lines.push("  Last sync: none recorded");
   }
@@ -2185,6 +2327,8 @@ async function runMessagesAgent() {
   const userId = requiredConfigString(config.userId, "userId");
   const agentToken = requiredConfigString(config.agentToken, "agentToken");
   const channel = setRuntimeLaunchAgentChannel(config.channel);
+  const deviceId = loadOrCreateShepherdDeviceId(channel);
+  const agentMetadata = { deviceId, agentVersion: PACKAGE_VERSION, agentChannel: channel };
   mergeShepherdOwnedMessageHandles(config.excludedMessageHandles);
   const backfillOverride = args["backfill-days"] ?? process.env.SHEPHERD_BACKFILL_DAYS;
   const backfillExplicit = backfillOverride !== undefined && backfillOverride !== null && backfillOverride !== "";
@@ -2199,9 +2343,9 @@ async function runMessagesAgent() {
 
   const kit = await import("@photon-ai/imessage-kit");
   const sdk = new kit.IMessageSDK({ debug: args.debug === true });
-  const sender = new MessagesBatchSender(apiUrl, agentToken, userId, channel);
+  const sender = new MessagesBatchSender(apiUrl, agentToken, userId, channel, agentMetadata);
   const contactLookup = createMutableContactLookup(buildContactLookup({ userId, channel }));
-  const serializer = createMessageSerializer(kit, contactLookup);
+  const serializer = createMessageSerializer(kit, contactLookup, agentMetadata);
   const stateCache = createMessageStateCache(userId, MESSAGES_STATE_CACHE_MAX, channel);
   const backfillGate = createMessagesBackfillGate();
   const contactSync = startMessagesContactSync(sender, contactLookup, {
@@ -2423,10 +2567,15 @@ async function runCodingSessionsAgent() {
       startedAt,
       finishedAt: new Date().toISOString(),
       scanned: scan.sessions.length,
+      uploadable: scan.sessions.length,
+      filesDiscovered: scan.filesDiscovered ?? scan.sessions.length,
+      filesSelected: scan.filesSelected ?? scan.sessions.length,
+      filesIgnored: Math.max(0, Number(scan.filesDiscovered ?? scan.sessions.length) - scan.sessions.length),
       changed: changed.length,
       selected: selected.length,
       sent: sendResult,
       parserVersion: CODING_SESSION_PARSER_VERSION,
+      providerStatus: codingSessionsProviderStatus(scan, previous, selected),
       command: command ? {
         id: command.id,
         type: command.type,
@@ -6423,6 +6572,8 @@ Options:
   --email <email>            Advanced: must match the WorkOS-authenticated email.
   --name <name>              Full name.
   --org <name>               Organization name.
+  --github-token <token>     GitHub PAT for repository API and webhook setup.
+  --github-repo <owner/repo> GitHub repository to sync with webhook coverage.
   --granola-api-key <key>    Legacy Granola API key fallback.
   --messages-handle <value>  Messages phone number or Apple ID email; comma-separate both if needed.
   --messages-chat-ids <ids>  Comma-separated local Messages chat IDs selected from messages-chats, or all to watch every current and future chat.
@@ -6435,7 +6586,7 @@ Options:
   --no-open-granola          Do not open Granola OAuth/API key setup.
   --no-messages              Skip local Messages.
   --coding-sessions          Opt in to local Codex/Claude Code session metadata sync.
-  --sources <list>           Exact sources to connect: google,notion,slack,granola,messages,coding-sessions,all.
+  --sources <list>           Exact sources to connect: google,notion,slack,github,granola,messages,coding-sessions,all.
   --add-sources <list>       Same as --sources, named for second-time onboarding.
   --no-install-messages-agent
                              Save Messages credentials without starting launchd.
@@ -6560,6 +6711,7 @@ function printAgentContract() {
     optionalContinueArgs: [
       "--messages-handle \"<phone_or_apple_id[,apple_id]>\" if local Messages is being connected",
       "--messages-chat-ids \"<comma_separated_chat_ids>\" if local Messages is being connected, or --messages-chat-ids all when the user explicitly wants every current and future Messages chat watched",
+      "--github-token \"<github_pat>\" and --github-repo \"<owner/repo>\" if GitHub is being connected",
       "--granola-api-key \"<legacy_granola_key>\" only when Granola falls back to legacy API-key setup",
     ],
     statusCommand: `${command} status`,
@@ -6609,7 +6761,7 @@ Common user requests:
 
 Start with selection questions to determine intent:
 1. Organization: Join existing org, or Create new org.
-2. Sources: Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts), Notion, Slack, Granola, Messages, Coding Sessions (Codex/Claude Code metadata). Allow multi-select if your interface supports it.
+2. Sources: Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts), Notion, Slack, GitHub, Granola, Messages, Coding Sessions (Codex/Claude Code metadata). Allow multi-select if your interface supports it.
 3. Messages, if selected: Skip Messages, or Provide handle.
 4. MCP install after onboarding completes: Codex, Claude Code, both, or none.
 
@@ -6651,7 +6803,7 @@ Add skip flags for sources the user did not select:
 Or pass an exact source list, especially for adding sources later:
   ${command} agent --add-sources coding-sessions --name "<full_name>" --org "<organization>"
 
-That command creates/reuses the customer user and org, saves local state, and opens at most one source setup surface. It works one modality at a time after account setup: Google Workspace, then Notion, then Slack, then Granola. If Messages details are still missing, it prints the Messages selector command instead of opening another auth surface. Do not manually open later source setup surfaces until the command tells you that source is the current modality.
+That command creates/reuses the customer user and org, saves local state, and opens at most one source setup surface. It works one modality at a time after account setup: Google Workspace, then Notion, then Slack, then GitHub, then Granola. If Messages details are still missing, it prints the Messages selector command instead of opening another auth surface. Do not manually open later source setup surfaces until the command tells you that source is the current modality.
 
 If Google Workspace is the current modality, the setup command opens the Admin Console domain-wide delegation page. Show this setup to the user and have their Google Workspace super admin authorize it:
 
@@ -6669,6 +6821,8 @@ Shepherd must still enforce selected users and groups internally before polling
 
 If Slack is the current modality 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. Do not open Granola or Messages until Slack is complete and the continue command advances.
 
+If GitHub is the current modality, do not use browser OAuth as the primary setup. Ask the user for a GitHub fine-grained or classic PAT and exact owner/repo, then continue with --github-token and --github-repo. Shepherd uses this path to create the repository webhook; OAuth-only GitHub is tools-only and does not provide full event sync coverage.
+
 If Granola is the current modality, the command opens Granola browser authorization when OAuth is configured. Leave the browser tab for the user and ask them to complete authorization before continuing.
 
 If the command reports the legacy Granola API-key fallback, it opens the Granola desktop app. If your local app automation can navigate it, go to:
@@ -6680,7 +6834,7 @@ If the legacy Granola API-key fallback is needed and Granola did not come forwar
 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 the current modality is complete, run:
-  ${payload.continueCommand} --messages-handle "<phone_or_apple_id[,apple_id]>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<legacy_granola_key>"
+  ${payload.continueCommand} --github-token "<github_pat>" --github-repo "<owner/repo>" --messages-handle "<phone_or_apple_id[,apple_id]>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<legacy_granola_key>"
 
 Omit any optional flag that is not being requested. Do not pass --granola-api-key after successful Granola browser authorization.
 
@@ -6867,6 +7021,32 @@ function channelRecord(channel) {
   return channel === STABLE_CHANNEL ? {} : { channel };
 }
 
+function shepherdDeviceIdFile(channel = cliChannel()) {
+  const dir = join(homedir(), ".shepherd");
+  mkdirSync(dir, { recursive: true });
+  return join(dir, `${channelFilePrefix(normalizeLaunchAgentChannel(channel))}device-id`);
+}
+
+function loadOrCreateShepherdDeviceId(channel = cliChannel()) {
+  const path = shepherdDeviceIdFile(channel);
+  try {
+    const existing = readFileSync(path, "utf8").trim();
+    if (isUuid(existing)) return existing.toLowerCase();
+  } catch {
+    // Missing or unreadable device id will be repaired below.
+  }
+
+  const next = randomUUID();
+  const tmpFile = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmpFile, `${next}\n`, { mode: 0o600 });
+  renameSync(tmpFile, path);
+  return next;
+}
+
+function isUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(String(value ?? "").trim());
+}
+
 async function updateAgentStateFromOnboardingResponse(state, response) {
   const authUrls = stringRecord(response?.authUrls);
   const hasAuthUrls = Object.keys(authUrls).length > 0;
@@ -7012,17 +7192,13 @@ async function openNextAgentModality({ sources, authUrls = {}, noOpen = false, p
     }
 
     if (source === "github") {
-      const url = typeof authUrls.github === "string" ? authUrls.github : null;
-      if (!url) {
-        return {
-          source,
-          label: "GitHub",
-          opened: false,
-          message: "GitHub authorization URL was not returned by Shepherd.",
-        };
-      }
-      await openOrPrint(url, { noOpen });
-      return { source, label: "GitHub", opened: !noOpen, url };
+      return {
+        source,
+        label: "GitHub",
+        opened: false,
+        patRequired: true,
+        message: "Provide --github-token and --github-repo so Shepherd can create the repository webhook; OAuth alone is tools-only and does not provide full event sync coverage.",
+      };
     }
 
     if (source === "granola") {
@@ -7104,14 +7280,8 @@ function printAgentCurrentAction(action, opts = {}) {
   }
 
   if (action.source === "github") {
-    if (action.opened) {
-      console.log("Opened GitHub authorization in the browser.");
-    } else if (action.url) {
-      console.log(`GitHub authorization URL: ${action.url}`);
-    } else if (action.message) {
-      console.log(action.message);
-    }
-    console.log("Ask the user to complete GitHub authorization before opening another source.");
+    console.log(action.message ?? "Provide a GitHub PAT and owner/repo for webhook-backed event sync.");
+    console.log("Do not use browser OAuth as the primary GitHub setup path for event coverage.");
     return;
   }
 
@@ -7148,7 +7318,7 @@ function agentNeedsUserAction(sources, action) {
   if (action.source === "google") return ["Have the customer's Google Workspace super admin authorize Shepherd's domain-wide delegation Client ID and scopes in Google Admin Console."];
   if (action.source === "notion") return ["Complete Notion browser authorization."];
   if (action.source === "slack") return ["Complete Slack browser authorization."];
-  if (action.source === "github") return ["Complete GitHub browser authorization."];
+  if (action.source === "github") return ["Provide --github-token and --github-repo so Shepherd can create the repository webhook; OAuth alone is tools-only and does not provide full event sync coverage."];
   if (action.source === "granola") return [action.url ? "Complete Granola browser authorization." : "Create/copy a legacy Granola API key from the Granola Mac app."];
   if (action.source === "messages") return ["Grant or confirm macOS Full Disk Access for the onboarding app and Node.js, run messages-chats, have the user select local Messages contacts/groups in the browser, then pass the printed chat IDs with the Messages handle."];
   if (action.source === "codingSessions") return ["Run the continue command to install local Codex and Claude Code session metadata sync."];
@@ -9428,6 +9598,9 @@ function startMessagesCommandPoller(opts) {
             allChats: opts.allChats,
             allowedChatIds: opts.allowedChatIds,
             queueDepth,
+            deviceId: opts.sender.deviceId,
+            agentVersion: opts.sender.agentVersion,
+            agentChannel: opts.sender.agentChannel,
           }),
         });
         clearMessagesAgentCommandState(opts.userId);
@@ -9534,6 +9707,9 @@ function messagesSourceSyncReceipt({
   allChats,
   allowedChatIds,
   queueDepth,
+  deviceId,
+  agentVersion = PACKAGE_VERSION,
+  agentChannel = cliChannel(),
 }) {
   const stored = countValue(result.totalStored);
   const updated = countValue(result.totalUpdated);
@@ -9548,7 +9724,9 @@ function messagesSourceSyncReceipt({
     sourceSyncRunId,
     commandId: command.id,
     provider: "imessage",
-    agentVersion: PACKAGE_VERSION,
+    deviceId,
+    agentVersion,
+    agentChannel,
     coverageFrom: coverageFrom ? coverageFrom.toISOString() : null,
     coverageTo: coverageTo.toISOString(),
     highWatermark: receiptWatermark(`${sourceSyncRunId}:imessage-rowid:${countValue(result.watermark)}`),
@@ -10246,11 +10424,20 @@ function snapshotContactMappings(mappings) {
   return new Map(mappings.map((mapping) => [mapping.handle, mapping.name]));
 }
 
-function createMessageSerializer(kit, contactLookup = emptyContactLookup()) {
+function createMessageSerializer(kit, contactLookup = emptyContactLookup(), agentMetadata = {}) {
   const chatNames = new Map();
   const isImageAttachment = kit.isImageAttachment ?? (() => false);
   const isVideoAttachment = kit.isVideoAttachment ?? (() => false);
   const isAudioAttachment = kit.isAudioAttachment ?? (() => false);
+  const deviceId = typeof agentMetadata.deviceId === "string" && agentMetadata.deviceId.trim()
+    ? agentMetadata.deviceId.trim()
+    : null;
+  const agentVersion = typeof agentMetadata.agentVersion === "string" && agentMetadata.agentVersion.trim()
+    ? agentMetadata.agentVersion.trim()
+    : PACKAGE_VERSION;
+  const agentChannel = typeof agentMetadata.agentChannel === "string" && agentMetadata.agentChannel.trim()
+    ? normalizeLaunchAgentChannel(agentMetadata.agentChannel)
+    : cliChannel();
 
   return {
     setChatName(chatId, name) {
@@ -10266,6 +10453,9 @@ function createMessageSerializer(kit, contactLookup = emptyContactLookup()) {
         messageId: String(providerMessageGuid?.value ?? msg.messageId ?? msg.rowId),
         providerMessageGuid: providerMessageGuid == null ? null : String(providerMessageGuid.value),
         _provider_guid_explicit: providerMessageGuid == null ? null : providerMessageGuid.explicit,
+        deviceId,
+        agentVersion,
+        agentChannel,
         localRowId: Number(msg.rowId ?? 0),
         rowId: Number(msg.rowId ?? 0),
         text: msg.text ?? null,
@@ -10734,7 +10924,8 @@ function codingSessionsCommandScanOptions(command) {
   if (type === "source_sync") {
     return {
       exhaustive: true,
-      fullInventory: true,
+      maxFiles: maxFiles ?? DEFAULT_CODING_SESSION_FILES_PER_PROVIDER,
+      ...(providers.length ? { providers } : {}),
     };
   }
   return {
@@ -10748,7 +10939,7 @@ function codingSessionsCommandPlan(command, scan, previousState) {
   if (!command) return { sessions: [], force: false, exactSelection: false, result: base };
   const payload = objectValue(command.payload) ?? {};
   const type = stringValue(command.type);
-  const maxFiles = positiveCommandInteger(payload.maxFiles) ?? 100;
+  const maxFiles = positiveCommandInteger(payload.maxFiles) ?? DEFAULT_CODING_SESSION_FILES_PER_PROVIDER;
   const force = type === "force_rescan" ? true : payload.force === false ? false : true;
 
   if (type === "source_sync") {
@@ -10866,7 +11057,8 @@ function codingSessionsSourceSyncReceipt({
     finishedAt,
     coverageFrom: Object.prototype.hasOwnProperty.call(payload, "coverageFrom") ? stringValue(payload.coverageFrom) : null,
     coverageTo: stringValue(payload.coverageTo) ?? finishedAt,
-    fullInventory: true,
+    fullInventory: scan.capped !== true,
+    maxFilesPerProvider: positiveCommandInteger(payload.maxFiles) ?? DEFAULT_CODING_SESSION_FILES_PER_PROVIDER,
     exhausted: failedCount === 0 && pendingUploads === 0,
     capHit: scan.capped === true,
     highWatermark,
@@ -10906,6 +11098,7 @@ function selectCodingSessionsPerProvider(sessions, maxFilesPerProvider) {
 
 function codingSessionsCommandDiagnostics(scan, previousState) {
   const providerCounts = {};
+  const providerStatus = codingSessionsProviderStatus(scan, previousState, []);
   let userMessages = 0;
   let agentResponses = 0;
   let sessionsWithVisibleTranscript = 0;
@@ -10922,7 +11115,10 @@ function codingSessionsCommandDiagnostics(scan, previousState) {
   return {
     parserVersion: CODING_SESSION_PARSER_VERSION,
     scanned: scan.sessions.length,
+    uploadable: scan.sessions.length,
     filesDiscovered: scan.filesDiscovered ?? scan.sessions.length,
+    filesSelected: scan.filesSelected ?? scan.sessions.length,
+    filesIgnored: Math.max(0, Number(scan.filesDiscovered ?? scan.sessions.length) - scan.sessions.length),
     filesParsed: scan.filesParsed ?? scan.sessions.length,
     capped: scan.capped === true,
     unchanged,
@@ -10931,11 +11127,42 @@ function codingSessionsCommandDiagnostics(scan, previousState) {
     userMessages,
     agentResponses,
     providerCounts,
+    providerStatus,
     probes: sanitizeCodingSessionProbes(scan.probes),
     errors: sanitizeCodingSessionErrors(scan.errors),
   };
 }
 
+function codingSessionsProviderStatus(scan, previousState, selectedSessions = []) {
+  const status = {};
+  const inventory = scan.providerStatus && typeof scan.providerStatus === "object" && !Array.isArray(scan.providerStatus)
+    ? scan.providerStatus
+    : {};
+  for (const provider of ["codex", "claude"]) {
+    const providerSessions = scan.sessions.filter((session) => session.provider === provider);
+    const selected = selectedSessions.filter((session) => session.provider === provider);
+    const unchanged = providerSessions.filter((session) => previousState.hashes?.[session.sourcePathHash] === session.contentHash).length;
+    const raw = inventory[provider] && typeof inventory[provider] === "object" && !Array.isArray(inventory[provider])
+      ? inventory[provider]
+      : {};
+    const filesDiscovered = countValue(raw.filesDiscovered);
+    const filesSelected = countValue(raw.filesSelected);
+    const uploadable = providerSessions.length;
+    status[provider] = {
+      filesDiscovered,
+      filesSelected,
+      filesIgnored: Math.max(0, filesDiscovered - uploadable),
+      uploadable,
+      scanned: uploadable,
+      unchanged,
+      changed: Math.max(0, uploadable - unchanged),
+      selected: selected.length,
+      capped: raw.capped === true,
+    };
+  }
+  return status;
+}
+
 function sanitizeCodingSessionProbes(probes) {
   if (!Array.isArray(probes)) return [];
   return probes.map((probe) => ({
@@ -11008,7 +11235,9 @@ async function scanCodingSessions(config, previousState = { hashes: {} }, option
     probes,
     errors,
     filesDiscovered: inventory.filesDiscovered,
+    filesSelected: files.length,
     filesParsed: sessions.length,
+    providerStatus: inventory.providerStatus,
     capped: inventory.capped,
     sessions,
     previousState,
@@ -11093,9 +11322,23 @@ async function codingSessionJsonlFiles({ codexDirs, claudeDir, errors, maxFilesP
     ...newestCodingSessionFiles(claudeFiles, maxFilesPerProvider),
   ].sort((a, b) => b.mtimeMs - a.mtimeMs || a.provider.localeCompare(b.provider) || a.path.localeCompare(b.path));
   const filesDiscovered = codexFiles.length + claudeFiles.length;
+  const providerStatus = {
+    codex: {
+      filesDiscovered: codexFiles.length,
+      filesSelected: Math.min(codexFiles.length, maxFilesPerProvider),
+      capped: codexFiles.length > maxFilesPerProvider,
+    },
+    claude: {
+      filesDiscovered: claudeFiles.length,
+      filesSelected: Math.min(claudeFiles.length, maxFilesPerProvider),
+      capped: claudeFiles.length > maxFilesPerProvider,
+    },
+  };
   return {
     files,
     filesDiscovered,
+    filesSelected: files.length,
+    providerStatus,
     capped: files.length < filesDiscovered,
   };
 }
@@ -11749,6 +11992,11 @@ class MessagesBatchSender {
     this.agentToken = agentToken;
     this.userId = userId;
     this.channel = normalizeLaunchAgentChannel(channel);
+    this.deviceId = typeof options.deviceId === "string" && options.deviceId.trim() ? options.deviceId.trim() : null;
+    this.agentVersion = typeof options.agentVersion === "string" && options.agentVersion.trim() ? options.agentVersion.trim() : PACKAGE_VERSION;
+    this.agentChannel = typeof options.agentChannel === "string" && options.agentChannel.trim()
+      ? normalizeLaunchAgentChannel(options.agentChannel)
+      : this.channel;
     this.queueFile = join(homedir(), ".shepherd", "raw-messages", `${channelFilePrefix(this.channel)}${safeFileId(userId)}-queue.json`);
     this.sendChain = Promise.resolve();
     this.batchSize = clampInt(Number(options.batchSize ?? MESSAGES_UPLOAD_BATCH_SIZE), 1, 10_000);
@@ -11825,13 +12073,14 @@ class MessagesBatchSender {
   }
 
   async postBatch(messages) {
+    const messagesWithMetadata = messages.map((message) => this.withAgentMetadata(message));
     const res = await messagesAgentFetch(`${this.apiUrl}/api/imessage/ingest`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         "x-api-key": this.agentToken,
       },
-      body: JSON.stringify({ userId: this.userId, messages }),
+      body: JSON.stringify({ userId: this.userId, messages: messagesWithMetadata }),
     });
 
     const json = await res.json().catch(() => ({}));
@@ -11882,13 +12131,14 @@ class MessagesBatchSender {
   }
 
   async postLocalStatus(status) {
+    const statusWithMetadata = this.withAgentMetadata(publicMessagesBackfillStatus(status) ?? status);
     const res = await messagesAgentFetch(`${this.apiUrl}/api/imessage/ingest/local-status`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         "x-api-key": this.agentToken,
       },
-      body: JSON.stringify({ status: publicMessagesBackfillStatus(status) ?? status }),
+      body: JSON.stringify({ status: statusWithMetadata }),
     });
 
     const json = await res.json().catch(() => ({}));
@@ -11896,6 +12146,16 @@ class MessagesBatchSender {
     return json;
   }
 
+  withAgentMetadata(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+    return {
+      ...value,
+      ...(this.deviceId ? { deviceId: this.deviceId } : {}),
+      agentVersion: this.agentVersion,
+      agentChannel: this.agentChannel,
+    };
+  }
+
   async fetchCommand() {
     const res = await messagesAgentFetch(`${this.apiUrl}/api/imessage/ingest/command`, {
       headers: {