askshepherd 0.1.32 → 0.1.36

package/bin/shepherd-onboard.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
 import { execFile, execFileSync, spawn } from "node:child_process";
-import { constants as fsConstants, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { constants as fsConstants, existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync } from "node:fs";
+import { access, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { homedir, platform } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
 
 const DEFAULT_API_URL = "https://brain-api-customer-facing.up.railway.app";
 const PACKAGE_NAME = "askshepherd";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
-const PACKAGE_VERSION = "0.1.32";
+const PACKAGE_VERSION = "0.1.36";
 const MCP_SERVER_NAME = "shepherd";
 const PACKAGE_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
 const DEFAULT_AGENT_STATE_PATH = join(homedir(), ".shepherd", "raw-onboarding-agent.json");
@@ -22,7 +23,8 @@ const MAX_BATCH_SIZE = 50;
 const MAX_QUEUE_MESSAGES = 10_000;
 const DEFAULT_MESSAGE_CHAT_SEARCH_LIMIT = 200;
 const INITIAL_MESSAGE_CHAT_ROWS = 20;
-const AGENT_MODALITY_ORDER = ["google", "slack", "granola", "messages"];
+const ALL_MESSAGES_CHATS = "__shepherd_all_messages_chats__";
+const AGENT_MODALITY_ORDER = ["google", "slack", "granola", "messages", "codingSessions"];
 const SHEPHERD_LOGO_PATH = join(PACKAGE_DIR, "assets", "shepherd_G_vector_136033.png");
 const GRANOLA_API_KEYS_PATH = "/settings/integrations/api-keys";
 const GOOGLE_WORKSPACE_DELEGATION_ADMIN_URL = "https://admin.google.com/ac/owl/domainwidedelegation";
@@ -30,6 +32,15 @@ const MAC_FULL_DISK_ACCESS_URL = "x-apple.systempreferences:com.apple.settings.P
 const LEGACY_MAC_FULL_DISK_ACCESS_URL = "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles";
 const MESSAGES_CHAT_DB_PATH = join(homedir(), "Library", "Messages", "chat.db");
 const MESSAGES_ATTACHMENTS_DIR = join(homedir(), "Library", "Messages", "Attachments");
+const CODEX_SESSIONS_DIR = join(homedir(), ".codex", "sessions");
+const CODEX_ARCHIVED_SESSIONS_DIR = join(homedir(), ".codex", "archived_sessions");
+const CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
+const CONTACTS_WAL_PATH = join(homedir(), "Library", "Application Support", "AddressBook", "AddressBook-v22.abcddb-wal");
+const CONTACT_SYNC_DEBOUNCE_MS = 5_000;
+const CONTACT_SYNC_FALLBACK_MS = 30 * 60_000;
+const SHEPHERD_OWNED_MESSAGE_HANDLES = parseMessageHandleList(
+  process.env.SHEPHERD_OWNED_MESSAGE_HANDLES ?? process.env.SENDBLUE_NUMBER ?? "",
+);
 const GOOGLE_WORKSPACE_DELEGATION_APP_NAME = "Shepherd";
 const GOOGLE_WORKSPACE_DELEGATION_SERVICE_ACCOUNT_EMAIL =
   "gigabrain-delegation@shepherd-gigabrain.iam.gserviceaccount.com";
@@ -120,6 +131,10 @@ async function dispatch() {
     await runMessagesChatsCommand();
   } else if (command === "messages-agent") {
     await runMessagesAgent();
+  } else if (command === "coding-sessions-agent") {
+    await runCodingSessionsAgent();
+  } else if (command === "coding-sessions-status") {
+    await runCodingSessionsStatus();
   } else {
     throw new Error(`Unknown command: ${command}`);
   }
@@ -143,12 +158,7 @@ async function runOnboarding() {
   const name = stringArg("name") ?? authenticatedName(workosLogin.authenticated) ?? await valueOrPrompt("name", "Full name");
   const organizationName = await valueOrPrompt("org", "Organization name");
 
-  const sources = {
-    google: !args["no-google"],
-    slack: !args["no-slack"],
-    granola: !args["no-granola"],
-    messages: !args["no-messages"],
-  };
+  const sources = selectedSources();
 
   const session = await postJson(`${apiUrl}/onboarding/raw/session`, {
     email,
@@ -237,6 +247,29 @@ async function runOnboarding() {
     }
   }
 
+  if (finalized.connected?.codingSessions?.agentToken) {
+    const configPath = await writeCodingSessionsConfig({
+      apiUrl,
+      userId: session.sessionId,
+      agentToken: finalized.connected.codingSessions.agentToken,
+      intervalSeconds: Number(args["coding-sessions-interval-seconds"] ?? 60),
+    });
+
+    if (!args["no-install-coding-sessions-agent"]) {
+      const install = await installCodingSessionsAgent(configPath, session.sessionId).catch((err) => ({
+        error: safeError(err),
+      }));
+      if ("error" in install) {
+        console.log(`\nLocal coding-session credentials saved: ${configPath}`);
+        console.log(`Coding-session background sync was not started: ${install.error}`);
+      } else {
+        console.log(`\nLocal coding-session sync started: ${install.label}`);
+      }
+    } else {
+      console.log(`\nLocal coding-session credentials saved: ${configPath}`);
+    }
+  }
+
   const connected = Object.keys(finalized.connected ?? {});
   console.log(`\nConnected sources: ${connected.length ? connected.join(", ") : "none"}`);
 
@@ -280,6 +313,10 @@ async function runAgentOnboarding() {
     || args["no-slack"]
     || args["no-granola"]
     || args["no-messages"]
+    || args["no-coding-sessions"]
+    || args["coding-sessions"]
+    || stringArg("sources")
+    || stringArg("add-sources")
   );
 
   if (!wantsStart) {
@@ -339,7 +376,7 @@ async function runAgentOnboarding() {
       currentAction,
       statePath,
       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>"`,
+      nextCommand: `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<granola_key>"`,
       needsUserAction: agentNeedsUserAction(sources, currentAction),
     }, null, 2));
     return;
@@ -358,7 +395,7 @@ async function runAgentOnboarding() {
   });
 
   console.log("\nAfter that modality is complete, 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(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<granola_key>"`);
   console.log("   Omit either optional flag if that source is not being connected.");
 }
 
@@ -869,7 +906,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, have the user select chats in the browser page, 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>" or --messages-chat-ids all.`);
   }
 
   const finalized = await postJson(
@@ -880,12 +917,19 @@ async function continueAgentOnboarding() {
   state = await updateAgentStateFromOnboardingResponse(state, finalized);
 
   if (finalized.connected?.messages?.agentToken) {
+    const selectedChats = selectedChatIdsIncludeAll(selectedMessageChatIds)
+      ? [allMessagesChatsSelection()]
+      : await loadSelectedMessageChatsForConfig(selectedMessageChatIds).catch((err) => {
+          console.warn(`Could not load selected Messages chat metadata for contact hydration: ${safeError(err)}`);
+          return [];
+        });
     const configPath = await writeMessagesConfig({
       apiUrl: state.apiUrl,
       userId: state.sessionId,
       agentToken: finalized.connected.messages.agentToken,
       backfillDays: parseBackfillDays(args["messages-backfill-days"], null),
       allowedChatIds: selectedMessageChatIds,
+      selectedChats,
     });
 
     if (!args["no-install-messages-agent"]) {
@@ -902,6 +946,29 @@ async function continueAgentOnboarding() {
     }
   }
 
+  if (finalized.connected?.codingSessions?.agentToken) {
+    const configPath = await writeCodingSessionsConfig({
+      apiUrl: state.apiUrl,
+      userId: state.sessionId,
+      agentToken: finalized.connected.codingSessions.agentToken,
+      intervalSeconds: Number(args["coding-sessions-interval-seconds"] ?? 60),
+    });
+
+    if (!args["no-install-coding-sessions-agent"]) {
+      const install = await installCodingSessionsAgent(configPath, state.sessionId).catch((err) => ({
+        error: safeError(err),
+      }));
+      if ("error" in install) {
+        console.log(`Coding-session credentials saved: ${configPath}`);
+        console.log(`Coding-session background sync was not started: ${install.error}`);
+      } else {
+        console.log(`Coding-session background sync started: ${install.label}`);
+      }
+    } else {
+      console.log(`Coding-session credentials saved: ${configPath}`);
+    }
+  }
+
   const errors = finalized.errors && Object.keys(finalized.errors).length ? finalized.errors : null;
   const currentAction = errors
     ? await openNextAgentModality({
@@ -915,11 +982,12 @@ async function continueAgentOnboarding() {
     console.log(JSON.stringify({
       status: errors ? "waiting" : "completed",
       connected: Object.keys(finalized.connected ?? {}),
+      alreadyConnected: Object.keys(finalized.alreadyConnected ?? {}),
       processingEnabled: finalized.processingEnabled === true,
       processing: finalized.processing,
       errors: errors ? safeErrorRecord(errors) : undefined,
       currentAction,
-      nextCommand: errors ? `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"` : undefined,
+      nextCommand: errors ? `${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<granola_key>"` : undefined,
       mcpInstall: errors ? undefined : {
         prompt: "Ask where to install Shepherd MCP for this customer: Codex, Claude Code, Cursor, any subset, or none.",
         targets: MCP_INSTALL_TARGETS,
@@ -940,7 +1008,7 @@ async function continueAgentOnboarding() {
     });
 
     console.log("\nAfter that modality is complete, rerun:");
-    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(`   ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<granola_key>"`);
     console.log("   Omit either optional flag if that source is not being connected.");
     return;
   }
@@ -982,8 +1050,10 @@ async function runMessagesChatsCommand() {
 
   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).`);
+    const selectedIds = selectedIncludesAllChats(selected) ? "all" : selected.map((chat) => chat.chatId).join(",");
+    console.log(selectedIncludesAllChats(selected)
+      ? "\nSelected all current and future Messages chats."
+      : `\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}"`);
@@ -997,6 +1067,7 @@ async function runMessagesChatsCommand() {
   }
   console.log("\nPass selected IDs to:");
   console.log(`  ${agentCommand()} agent --continue --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<id1>,<id2>"`);
+  console.log(`  Or explicitly sync all current and future chats with: --messages-chat-ids all`);
 }
 
 async function runMessagesAgent() {
@@ -1007,37 +1078,157 @@ async function runMessagesAgent() {
   const apiUrl = requiredConfigString(config.apiUrl, "apiUrl");
   const userId = requiredConfigString(config.userId, "userId");
   const agentToken = requiredConfigString(config.agentToken, "agentToken");
+  mergeShepherdOwnedMessageHandles(config.excludedMessageHandles);
   const backfillDays = parseBackfillDays(args["backfill-days"] ?? process.env.SHEPHERD_BACKFILL_DAYS ?? config.backfillDays, null);
   const allowedChatIds = parseAllowedChatIds(config.allowedChatIds);
-  if (allowedChatIds.length === 0) {
-    throw new Error("Messages config must include selected chat IDs. Re-run onboarding and select one or more recent Messages chats.");
+  const allChats = config.allChats === true || selectedChatIdsIncludeAll(allowedChatIds);
+  if (!allChats && allowedChatIds.length === 0) {
+    throw new Error("Messages config must include selected chat IDs or allChats=true. Re-run onboarding and select chats, or pass --messages-chat-ids all.");
   }
 
   const kit = await import("@photon-ai/imessage-kit");
   const sdk = new kit.IMessageSDK({ debug: args.debug === true });
   const sender = new MessagesBatchSender(apiUrl, agentToken, userId);
-  const contactLookup = buildContactLookup();
+  const contactLookup = createMutableContactLookup(buildContactLookup());
   const serializer = createMessageSerializer(kit, contactLookup);
+  const contactSync = startMessagesContactSync(sender, contactLookup, {
+    syncAllContacts: allChats,
+    seedHandles: allChats ? [] : selectedChatContactSeedHandles(config.selectedChats, allowedChatIds),
+  });
 
   console.log("Shepherd Messages raw sync starting");
-  console.log(`Messages chat filter: ${allowedChatIds.length} selected chat(s)`);
+  console.log(allChats
+    ? "Messages chat filter: all current and future chats"
+    : `Messages chat filter: ${allowedChatIds.length} selected chat(s)`);
 
   try {
+    await contactSync.syncNow({ forceAll: true, reason: "startup" }).catch((err) => {
+      console.error("Initial Messages contact sync failed:", safeError(err));
+    });
     await loadGroupChatNames(sdk, serializer);
     loadSelectedChatNames(config.selectedChats, serializer);
 
     if (backfillDays !== 0) {
-      await runMessagesBackfill(sdk, sender, serializer, backfillDays, allowedChatIds);
+      await runMessagesBackfill(sdk, sender, serializer, backfillDays, allChats ? null : allowedChatIds, contactSync);
+      await contactSync.syncNow({ forceAll: true, reason: "post-backfill" }).catch((err) => {
+        console.error("Post-backfill Messages contact sync failed:", safeError(err));
+      });
     }
 
-    await gapFillFromWatermark(sdk, sender, serializer, userId, allowedChatIds);
-    await watchMessages(sdk, sender, serializer, userId, allowedChatIds);
+    await gapFillFromWatermark(sdk, sender, serializer, userId, allChats ? null : allowedChatIds, contactSync);
+    await contactSync.syncNow({ forceAll: true, reason: "post-gap-fill" }).catch((err) => {
+      console.error("Post-gap-fill Messages contact sync failed:", safeError(err));
+    });
+    await watchMessages(sdk, sender, serializer, userId, allChats ? null : allowedChatIds, { contactSync });
   } catch (err) {
+    contactSync.stop();
     await sdk.close?.().catch(() => undefined);
     throw err;
   }
 }
 
+async function runCodingSessionsAgent() {
+  const configPath = stringArg("config");
+  if (!configPath) throw new Error("coding-sessions-agent requires --config <path>");
+
+  const config = JSON.parse(await readFile(configPath, "utf8"));
+  const apiUrl = requiredConfigString(config.apiUrl, "apiUrl");
+  const userId = requiredConfigString(config.userId, "userId");
+  const agentToken = requiredConfigString(config.agentToken, "agentToken");
+  const sender = new CodingSessionsBatchSender(apiUrl, agentToken, userId);
+  const statePath = codingSessionsStateFile(userId);
+  const statusPath = codingSessionsStatusFile(userId);
+  const intervalSeconds = Math.max(15, Math.floor(Number(args["interval-seconds"] ?? config.intervalSeconds ?? 60)));
+
+  console.log("Shepherd Coding Sessions sync starting");
+  while (true) {
+    const startedAt = new Date().toISOString();
+    const previous = readCodingSessionsState(statePath);
+    const scan = await scanCodingSessions(config, previous);
+    const changed = scan.sessions.filter((session) => previous.hashes[session.sourcePathHash] !== session.contentHash);
+    const sendResult = changed.length > 0 ? await sender.send(changed) : { stored: 0, updated: 0, skipped: 0 };
+    const nextState = {
+      hashes: { ...previous.hashes },
+      updatedAt: new Date().toISOString(),
+    };
+    for (const session of changed) {
+      nextState.hashes[session.sourcePathHash] = session.contentHash;
+    }
+    writeFileSync(statePath, JSON.stringify(nextState, null, 2), { mode: 0o600 });
+    const status = {
+      ok: true,
+      startedAt,
+      finishedAt: new Date().toISOString(),
+      scanned: scan.sessions.length,
+      changed: changed.length,
+      sent: sendResult,
+      probes: scan.probes,
+      errors: scan.errors,
+    };
+    writeFileSync(statusPath, JSON.stringify(status, null, 2), { mode: 0o600 });
+    console.log(`Coding session scan: ${scan.sessions.length} scanned, ${changed.length} changed, ${sendResult.stored ?? 0} stored, ${sendResult.updated ?? 0} updated, ${sendResult.skipped ?? 0} skipped`);
+
+    if (args.once) return;
+    await sleep(intervalSeconds * 1000);
+  }
+}
+
+async function runCodingSessionsStatus() {
+  const configPath = stringArg("config") ?? await latestCodingSessionsConfigPath();
+  const config = configPath ? JSON.parse(await readFile(configPath, "utf8")) : null;
+  const userId = config?.userId ?? null;
+  const safeId = userId ? safeFileId(userId) : null;
+  const label = safeId ? `ai.shepherd.coding-sessions.${safeId}` : null;
+  const probes = await probeCodingSessionPaths(config ?? {});
+  const lastSync = userId ? readJsonOptional(codingSessionsStatusFile(userId)) : null;
+  const queue = userId ? readJsonOptional(join(homedir(), ".shepherd", "coding-sessions", `${safeFileId(userId)}-queue.json`)) : null;
+  const launch = label && platform() === "darwin"
+    ? {
+        label,
+        state: readLaunchctlPrint(`gui/${process.getuid?.() ?? 501}/${label}`),
+      }
+    : null;
+  const production = await productionOnboardingStatusForCodingSessions(config).catch((err) => ({ error: safeError(err) }));
+  const status = {
+    configPath: configPath ?? null,
+    userId,
+    localFolders: probes,
+    launch,
+    lastSync,
+    queueDepth: Array.isArray(queue) ? queue.length : 0,
+    production,
+  };
+
+  if (args.json) {
+    console.log(JSON.stringify(status, null, 2));
+    return;
+  }
+
+  console.log("\nShepherd coding-session sync status\n");
+  console.log(`Config: ${configPath ?? "not found"}`);
+  if (userId) console.log(`User: ${userId}`);
+  for (const probe of probes) {
+    console.log(`- ${probe.provider}: ${probe.path} ${probe.readable ? "readable" : `not readable (${probe.reason})`}`);
+  }
+  if (launch) {
+    const running = /state = running|job state = running/i.test(launch.state);
+    console.log(`LaunchAgent: ${launch.label} ${running ? "running" : "not running or unknown"}`);
+  } else {
+    console.log("LaunchAgent: not installed or unavailable");
+  }
+  if (lastSync) {
+    console.log(`Last sync: ${lastSync.finishedAt ?? "unknown"} (${lastSync.scanned ?? 0} scanned, ${lastSync.changed ?? 0} changed)`);
+  } else {
+    console.log("Last sync: none recorded");
+  }
+  console.log(`Queued unsent sessions: ${Array.isArray(queue) ? queue.length : 0}`);
+  if (production?.providers?.codingSessions) {
+    console.log(`Production provider: ${production.providers.codingSessions.connected ? "connected" : "not connected"}`);
+  } else if (production?.error) {
+    console.log(`Production provider: unavailable (${production.error})`);
+  }
+}
+
 function parseArgs(argv) {
   const parsed = {};
   for (let i = 0; i < argv.length; i++) {
@@ -1070,8 +1261,10 @@ 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 agent --continue --granola-api-key <key> --messages-handle <value> --messages-chat-ids <ids>
+  npx -y ${PACKAGE_NAME}@latest agent --continue --granola-api-key <key> --messages-handle <value> --messages-chat-ids <ids|all>
+  npx -y ${PACKAGE_NAME}@latest agent --add-sources coding-sessions --name <name> --org <organization>
   npx -y ${PACKAGE_NAME}@latest agent --status
+  npx -y ${PACKAGE_NAME}@latest coding-sessions-status
   npx -y ${PACKAGE_NAME}@latest messages-chats
   npx -y ${PACKAGE_NAME}@latest granola-api-keys
 
@@ -1081,6 +1274,40 @@ The bare agent command is intended for coding-agent shells. For direct terminal
     return;
   }
 
+  if (which === "coding-sessions-agent") {
+    console.log(`Shepherd coding-session sync agent
+
+Usage:
+  shepherd-onboard coding-sessions-agent --config ~/.shepherd/coding-sessions/<id>.json
+
+Options:
+  --config <path>            Coding-session agent config created by onboarding.
+  --once                     Run one scan and exit.
+  --interval-seconds <n>     Poll interval for live sync. Defaults to config or 60.
+  --debug                    Print extra collector details.
+  --help                     Show this help.
+`);
+    return;
+  }
+
+  if (which === "coding-sessions-status") {
+    console.log(`Shepherd coding-session sync status
+
+Usage:
+  npx -y ${PACKAGE_NAME}@latest coding-sessions-status
+  npx -y ${PACKAGE_NAME}@latest coding-sessions-status --json
+
+Shows whether local Codex and Claude Code session folders are readable, whether
+the background LaunchAgent is installed/running, and the last local sync result.
+
+Options:
+  --config <path>            Config path. Defaults to the latest file in ~/.shepherd/coding-sessions.
+  --json                     Print machine-readable status.
+  --help                     Show this help.
+`);
+    return;
+  }
+
   if (which === "messages-agent") {
     console.log(`Shepherd Messages raw sync agent
 
@@ -1110,6 +1337,7 @@ macOS permission:
 
 Options:
   --limit <n>                Number of recent chats to load for search. Defaults to ${DEFAULT_MESSAGE_CHAT_SEARCH_LIMIT}.
+  --messages-chat-ids all    Supported on agent --continue to watch every current and future Messages chat.
   --text                     Print a terminal list instead of opening the selector page.
   --no-open                  Print the local selector URL instead of opening it.
   --no-permission-prompt     Print macOS permission instructions without waiting for confirmation.
@@ -1195,6 +1423,7 @@ Usage:
   npx -y ${PACKAGE_NAME}@latest mcp-login
   npx -y ${PACKAGE_NAME}@latest mcp-install
   npx -y ${PACKAGE_NAME}@latest messages-chats
+  npx -y ${PACKAGE_NAME}@latest coding-sessions-status
   npx -y ${PACKAGE_NAME}@latest granola-api-keys
 
 Options:
@@ -1203,7 +1432,7 @@ Options:
   --org <name>               Organization name.
   --granola-api-key <key>    Granola API key.
   --messages-handle <value>  Messages phone number or Apple ID email.
-  --messages-chat-ids <ids>  Comma-separated local Messages chat IDs selected from messages-chats.
+  --messages-chat-ids <ids>  Comma-separated local Messages chat IDs selected from messages-chats, or all to watch every current and future chat.
   --messages-backfill-days <days>
                              Local Messages backfill window. Defaults to all selected chat history.
   --no-google                Skip Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts).
@@ -1211,8 +1440,13 @@ Options:
   --no-granola               Skip Granola.
   --no-open-granola          Do not open the Granola API key screen.
   --no-messages              Skip local Messages.
+  --coding-sessions          Opt in to local Codex/Claude Code session summary sync.
+  --sources <list>           Exact sources to connect: google,slack,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.
+  --no-install-coding-sessions-agent
+                             Save coding-session credentials without starting launchd.
   --no-open                  Print auth URLs instead of opening the browser.
   --no-permission-prompt     Print macOS permission instructions without waiting for confirmation.
   --api <url>                Advanced: Shepherd API URL.
@@ -1255,9 +1489,11 @@ function printAgentContract() {
       "Tell the user Shepherd verifies existing-org joins from the authenticated WorkOS account and company email domain. The typed org name is not trusted by itself.",
       "If Google Workspace is selected, guide the customer's Google Workspace super admin to authorize Shepherd's Client ID and scopes in Google Admin Console.",
       "Ask Messages as a selectable choice: Skip Messages, or Provide handle.",
+      "Ask Coding Sessions as a selectable choice: Skip Coding Sessions, or Sync Codex/Claude Code session summaries.",
       "If the user chooses Provide handle, ask for the phone number or Apple ID email.",
       "If Messages is selected, ask the user to grant or confirm macOS Full Disk Access for the app running onboarding and the Node.js binary used by background sync. Shepherd checks this and keeps prompting until access works in interactive onboarding.",
-      "If Messages is selected, run the recent-chat command. It opens a browser selector with recent chats and search. Never sync all Messages chats by default.",
+      "If Messages is selected, run the recent-chat command. It opens a browser selector with recent chats and search. Never sync all Messages chats by default; use all only when the user explicitly asks for every current and future chat.",
+      "If Coding Sessions is selected, continue onboarding installs a local LaunchAgent that reads Codex and Claude Code session logs, summarizes them, and syncs summaries. It usually does not require Full Disk Access unless macOS denies access to ~/.codex or ~/.claude.",
       "After raw onboarding completes, ask whether they want Shepherd MCP installed for their signed-in customer account into Codex, Claude Code, Cursor, any subset, or none.",
     ],
     selectionQuestions: [
@@ -1269,7 +1505,7 @@ function printAgentContract() {
       {
         label: "Sources",
         prompt: "Which sources should Shepherd connect for raw sync?",
-        options: ["Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts)", "Slack", "Granola", "Messages"],
+        options: ["Google Workspace (Gmail/Drive/Docs/Calendar/Sheets/Slides/Tasks/Contacts)", "Slack", "Granola", "Messages", "Coding Sessions (Codex/Claude Code summaries)"],
         multiSelect: true,
       },
       {
@@ -1290,6 +1526,7 @@ function printAgentContract() {
       "Messages phone number or Apple ID email, if they want local Messages connected",
       "Full Disk Access confirmation, if they want local Messages connected on macOS",
       "Selected local Messages chats from the browser selector, if they want local Messages connected",
+      "Coding-session sync consent, if they want Codex and Claude Code session summaries connected",
       "MCP install targets after onboarding completes: Codex, Claude Code, Cursor, any subset, or none",
     ],
     afterStartCommand: [
@@ -1308,22 +1545,29 @@ function printAgentContract() {
     ],
     loginCommand: `${command} agent --login`,
     startCommand: `${command} agent --name "<full_name>" --org "<organization>"`,
+    addSourcesCommand: `${command} agent --add-sources coding-sessions --name "<full_name>" --org "<organization>"`,
     continueCommand: `${command} agent --continue`,
     mcpLoginCommand: `${command} mcp-login`,
     optionalContinueArgs: [
       "--messages-handle \"<phone_or_apple_id>\" if local Messages is being connected",
-      "--messages-chat-ids \"<comma_separated_chat_ids>\" 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",
       "--granola-api-key \"<granola_key>\" if Granola is being connected",
     ],
     statusCommand: `${command} agent --status`,
     messagesChatsCommand: `${command} messages-chats`,
     messagesPermissions: {
-      macOS: "Local Messages raw sync needs Full Disk Access for the app running onboarding and for Node.js used by the background LaunchAgent. The Messages selector command validates local chat.db access, opens Full Disk Access settings if needed, and keeps checking until access works in interactive onboarding. Background sync install also checks that launchd can start the Messages agent. Contacts permission may also appear when resolving local contact names.",
+      macOS: "Local Messages raw sync needs Full Disk Access for the app running onboarding and for Node.js used by the background LaunchAgent. The Messages selector command validates local chat.db access, opens Full Disk Access settings if needed, and keeps checking until access works in interactive onboarding. Background sync install also checks that launchd can start the Messages agent. Contacts permission may also appear when resolving local contact names. The background Messages agent reloads Contacts on startup, watches AddressBook changes when available, and runs fallback contact sync so renamed contacts can hydrate prior ingested Messages rows for the token-bound customer account.",
       nodeBinary: process.execPath,
     },
+    codingSessions: {
+      sourceFlag: "--sources coding-sessions or --add-sources coding-sessions",
+      statusCommand: `${command} coding-sessions-status`,
+      localAgentCommand: `${command} coding-sessions-agent --config ~/.shepherd/coding-sessions/<id>.json`,
+      privacy: "Shepherd uploads bounded summaries and evidence metadata, not full raw Codex or Claude Code transcripts. Secrets, auth headers, private keys, credential URLs, high-entropy tokens, and home paths are redacted.",
+    },
     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 production environment. Finalize asks production brain services to schedule downstream ingestion batches, wiki ingestion, memory artifacts, and document summaries. Local Messages starts via a macOS LaunchAgent when run on macOS.",
+    expectedResult: "Cloud sources start raw polling/backfill in the customer-facing Shepherd production environment. Finalize asks production brain services to schedule downstream ingestion batches, wiki ingestion, memory artifacts, document summaries, and coding-session wiki artifacts. Local Messages and Coding Sessions start via macOS LaunchAgents when run on macOS.",
     granolaApiKeyCommand: `${command} granola-api-keys`,
     granolaApiKeyPath: "Granola desktop app -> Settings -> Connectors -> API keys",
   };
@@ -1343,7 +1587,7 @@ Ask with short interactive prompts, not as one pasted checklist. Do not paste th
 
 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), 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, Coding Sessions (Codex/Claude Code summaries). 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, Cursor, any subset, or none.
 
@@ -1369,9 +1613,9 @@ If Messages is selected, run:
 
 Before or during this step, ask the user to grant or confirm macOS Full Disk Access for local Messages sync. The command validates access to the local Messages database, opens System Settings -> Privacy & Security -> Full Disk Access if access is missing, and keeps checking until access works in interactive onboarding. The user should enable the app running onboarding, such as Terminal, iTerm, Claude Code, or Codex, and Node.js for background sync:
   ${payload.messagesPermissions.nodeBinary}
-Contacts permission may also appear when Shepherd resolves local contact names.
+Contacts permission may also appear when Shepherd resolves local contact names. The background Messages agent reloads Contacts on startup, watches AddressBook changes when available, and runs fallback contact sync so renamed contacts can hydrate prior ingested Messages rows for the token-bound customer account.
 
-This opens a minimal local webpage with recent local Messages chats and search. 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.
+This opens a minimal local webpage with recent local Messages chats and search. Have the user select which contacts/groups Shepherd should sync. Do not select all chats by default. If the user explicitly wants everything, use the "Sync all current and future chats" checkbox or pass --messages-chat-ids all. All-chats mode backfills current chats and keeps watching chats that appear later. When the command returns, keep the printed chat IDs or the literal value all.
 
 Then run:
   ${payload.startCommand}
@@ -1382,6 +1626,9 @@ Add skip flags for sources the user did not select:
 - --no-granola
 - --no-messages
 
+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 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.
 
 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:
@@ -1409,13 +1656,18 @@ If Granola is the current modality and did not come forward, run:
 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>" --messages-chat-ids "<comma_separated_chat_ids>" --granola-api-key "<granola_key>"
+  ${payload.continueCommand} --messages-handle "<phone_or_apple_id>" --messages-chat-ids "<comma_separated_chat_ids_or_all>" --granola-api-key "<granola_key>"
 
 Omit either optional flag if that source is not being connected.
 
+If Coding Sessions was selected, the continue step installs local Codex/Claude Code session summary sync. It probes ~/.codex and ~/.claude, redacts sensitive strings, and uploads bounded summaries and work metadata rather than full transcripts. It usually does not need Full Disk Access unless macOS denies access to those folders.
+
 Check progress with:
   ${payload.statusCommand}
 
+Check local coding-session sync with:
+  ${payload.codingSessions.statusCommand}
+
 After onboarding completes, ask whether to install Shepherd MCP for the signed-in customer into Codex, Claude Code, Cursor, any subset, or none.
 If they choose any targets, run:
   ${payload.mcpLoginCommand} --install "<codex,claude,cursor>"
@@ -1432,12 +1684,74 @@ function hasIdentityArgs() {
 }
 
 function selectedSources() {
-  return {
-    google: !args["no-google"],
-    slack: !args["no-slack"],
-    granola: !args["no-granola"],
-    messages: !args["no-messages"],
+  const explicitSources = stringArg("sources") ?? stringArg("add-sources");
+  const selected = explicitSources
+    ? sourceSelectionFromList(explicitSources)
+    : {
+        google: !args["no-google"],
+        slack: !args["no-slack"],
+        granola: !args["no-granola"],
+        messages: !args["no-messages"],
+        codingSessions: args["coding-sessions"] === true || args["coding-sessions"] === "true",
+      };
+
+  if (args["no-google"]) selected.google = false;
+  if (args["no-slack"]) selected.slack = false;
+  if (args["no-granola"]) selected.granola = false;
+  if (args["no-messages"]) selected.messages = false;
+  if (args["no-coding-sessions"]) selected.codingSessions = false;
+  if (args["coding-sessions"]) selected.codingSessions = true;
+
+  return selected;
+}
+
+function sourceSelectionFromList(value) {
+  const selected = {
+    google: false,
+    slack: false,
+    granola: false,
+    messages: false,
+    codingSessions: false,
   };
+  const aliases = new Map([
+    ["google", "google"],
+    ["gmail", "google"],
+    ["drive", "google"],
+    ["docs", "google"],
+    ["gdocs", "google"],
+    ["calendar", "google"],
+    ["slack", "slack"],
+    ["granola", "granola"],
+    ["messages", "messages"],
+    ["imessage", "messages"],
+    ["imessages", "messages"],
+    ["coding-sessions", "codingSessions"],
+    ["coding_sessions", "codingSessions"],
+    ["codingsessions", "codingSessions"],
+    ["sessions", "codingSessions"],
+    ["codex", "codingSessions"],
+    ["claude", "codingSessions"],
+    ["claude-code", "codingSessions"],
+  ]);
+  const raw = String(value ?? "").trim().toLowerCase();
+  if (!raw) throw new Error("--sources requires at least one source.");
+  const parts = raw.split(/[,\s]+/).filter(Boolean);
+  for (const part of parts) {
+    if (part === "all") {
+      selected.google = true;
+      selected.slack = true;
+      selected.granola = true;
+      selected.messages = true;
+      selected.codingSessions = true;
+      continue;
+    }
+    const source = aliases.get(part);
+    if (!source) {
+      throw new Error(`Unknown source "${part}". Use google, slack, granola, messages, coding-sessions, or all.`);
+    }
+    selected[source] = true;
+  }
+  return selected;
 }
 
 async function writeAgentState(state) {
@@ -1618,6 +1932,16 @@ async function openNextAgentModality({ sources, authUrls = {}, noOpen = false, p
         message: "Run the local Messages chat selector and keep the printed chat IDs.",
       };
     }
+
+    if (source === "codingSessions") {
+      return {
+        source,
+        label: "Coding Sessions",
+        opened: false,
+        command: `${agentCommand()} agent --continue`,
+        message: "Continue onboarding to install local Codex and Claude Code session sync.",
+      };
+    }
   }
 
   return null;
@@ -1665,6 +1989,12 @@ function printAgentCurrentAction(action, opts = {}) {
     console.log(`Run: ${action.command}`);
     console.log("Have the user select specific local Messages chats; do not select all by default.");
     console.log("Ask the user to grant or confirm macOS Full Disk Access for the app running onboarding and Node.js before installing background Messages sync.");
+    return;
+  }
+
+  if (action.source === "codingSessions") {
+    console.log(`Run: ${action.command}`);
+    console.log("This installs a local LaunchAgent that summarizes Codex and Claude Code session logs and syncs those summaries to Shepherd.");
   }
 }
 
@@ -1674,6 +2004,7 @@ function agentNeedsUserAction(sources, action) {
   if (action.source === "slack") return ["Complete Slack browser authorization."];
   if (action.source === "granola") return ["Create/copy a 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 summary sync."];
   return [];
 }
 
@@ -1828,7 +2159,7 @@ async function explainMessagesBackgroundPermissions(opts = {}) {
   console.log("\nMessages background sync permissions");
   console.log("Local Messages raw sync runs as a macOS LaunchAgent using npx/Node.js. For continuous sync, macOS Full Disk Access must include the background Node.js binary, not just the current terminal.");
   printMessagesPermissionTargets();
-  console.log("Contacts permission may also appear when Shepherd resolves local contact names for selected chats.");
+  console.log("Contacts permission may also appear when Shepherd resolves local contact names. The background agent keeps contact names hydrated for observed Messages conversations.");
   await openFullDiskAccessSettings(opts);
 
   if (opts.waitForUser && process.stdin.isTTY && !args["no-permission-prompt"]) {
@@ -1940,8 +2271,9 @@ async function writeMessagesConfig(input) {
   await mkdir(dir, { recursive: true });
   const path = join(dir, `${input.userId}.json`);
   const allowedChatIds = parseAllowedChatIds(input.allowedChatIds);
-  if (allowedChatIds.length === 0) {
-    throw new Error("Select at least one Messages chat before installing local Messages sync.");
+  const allChats = selectedChatIdsIncludeAll(allowedChatIds);
+  if (!allChats && allowedChatIds.length === 0) {
+    throw new Error("Select at least one Messages chat or pass --messages-chat-ids all before installing local Messages sync.");
   }
   await writeFile(
     path,
@@ -1950,8 +2282,10 @@ async function writeMessagesConfig(input) {
       userId: input.userId,
       agentToken: input.agentToken,
       backfillDays: input.backfillDays,
-      allowedChatIds,
+      allChats,
+      allowedChatIds: allChats ? [] : allowedChatIds,
       selectedChats: Array.isArray(input.selectedChats) ? input.selectedChats.map(publicMessageChat) : [],
+      excludedMessageHandles: SHEPHERD_OWNED_MESSAGE_HANDLES,
       createdAt: new Date().toISOString(),
     }, null, 2),
     { mode: 0o600 },
@@ -2036,6 +2370,110 @@ async function installMessagesAgent(configPath, userId) {
   return { label, plistPath, stdoutPath, stderrPath };
 }
 
+async function writeCodingSessionsConfig(input) {
+  const dir = join(homedir(), ".shepherd", "coding-sessions");
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, `${input.userId}.json`);
+  await writeFile(
+    path,
+    JSON.stringify({
+      apiUrl: input.apiUrl,
+      userId: input.userId,
+      agentToken: input.agentToken,
+      intervalSeconds: Math.max(15, Math.floor(Number(input.intervalSeconds) || 60)),
+      codexDirs: [CODEX_SESSIONS_DIR, CODEX_ARCHIVED_SESSIONS_DIR],
+      claudeProjectsDir: CLAUDE_PROJECTS_DIR,
+      maxFilesPerProvider: 300,
+      createdAt: new Date().toISOString(),
+    }, null, 2),
+    { mode: 0o600 },
+  );
+  return path;
+}
+
+async function installCodingSessionsAgent(configPath, userId) {
+  if (platform() !== "darwin") {
+    throw new Error("automatic local coding-session sync is only supported on macOS");
+  }
+
+  const safeId = safeFileId(userId);
+  const label = `ai.shepherd.coding-sessions.${safeId}`;
+  const rawDir = join(homedir(), ".shepherd", "coding-sessions");
+  const agentsDir = join(homedir(), "Library", "LaunchAgents");
+  await mkdir(rawDir, { recursive: true });
+  await mkdir(agentsDir, { recursive: true });
+
+  const plistPath = join(agentsDir, `${label}.plist`);
+  const stdoutPath = join(rawDir, `${safeId}.out.log`);
+  const stderrPath = join(rawDir, `${safeId}.err.log`);
+  const launchPath = launchAgentPath();
+
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/bin/env</string>
+    <string>npx</string>
+    <string>-y</string>
+    <string>${PACKAGE_SPEC}</string>
+    <string>coding-sessions-agent</string>
+    <string>--config</string>
+    <string>${xmlEscape(configPath)}</string>
+  </array>
+  <key>KeepAlive</key>
+  <true/>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(stdoutPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(stderrPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(launchPath)}</string>
+  </dict>
+</dict>
+</plist>
+`;
+
+  await writeFile(plistPath, plist, { mode: 0o600 });
+  const stdoutOffset = await fileLength(stdoutPath);
+  const stderrOffset = await fileLength(stderrPath);
+  await execFileQuiet("launchctl", ["unload", plistPath], { ignoreError: true });
+  await execFileQuiet("launchctl", ["load", plistPath]);
+  await execFileQuiet("launchctl", ["start", label], { ignoreError: true });
+  await verifyCodingSessionsAgentLaunch({ label, stdoutPath, stderrPath, stdoutOffset, stderrOffset });
+  return { label, plistPath, stdoutPath, stderrPath };
+}
+
+async function verifyCodingSessionsAgentLaunch({ label, stdoutPath, stderrPath, stdoutOffset, stderrOffset }) {
+  const domainLabel = `gui/${process.getuid?.() ?? 501}/${label}`;
+  for (let attempt = 0; attempt < 8; attempt++) {
+    await sleep(1000);
+    const stdout = await readFileFrom(stdoutPath, stdoutOffset);
+    const stderr = await readFileFrom(stderrPath, stderrOffset);
+    const launchState = readLaunchctlPrint(domainLabel);
+
+    if (/Shepherd Coding Sessions sync starting|Coding session scan/i.test(stdout)
+      && /state = running|job state = running/i.test(launchState)) {
+      return;
+    }
+    if (/EACCES|operation not permitted|permission denied/i.test(stderr)) {
+      throw new Error("Coding-session sync could not read ~/.codex or ~/.claude. Grant the onboarding app access to those folders or run coding-sessions-status for details.");
+    }
+    if (/last exit code = [1-9]|job state = exited|state = spawn scheduled/i.test(launchState) && stderr.trim()) {
+      throw new Error(`Coding-session sync exited during startup: ${firstMeaningfulLine(stderr)}`);
+    }
+  }
+
+  throw new Error("Coding-session sync did not reach a healthy launchd running state. Check logs under ~/.shepherd/coding-sessions and run coding-sessions-status.");
+}
+
 async function verifyMessagesAgentLaunch({ label, stdoutPath, stderrPath, stdoutOffset, stderrOffset }) {
   const domainLabel = `gui/${process.getuid?.() ?? 501}/${label}`;
   for (let attempt = 0; attempt < 12; attempt++) {
@@ -2121,7 +2559,7 @@ async function selectRecentMessageChats() {
   }
 
   if (!process.stdin.isTTY) {
-    throw new Error(`Messages sync requires selected chat IDs. Run ${agentCommand()} messages-chats 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>" or --messages-chat-ids all.`);
   }
 
   const chats = await listRecentMessageChats({ limit: clampInt(Number(args.limit ?? DEFAULT_MESSAGE_CHAT_SEARCH_LIMIT), 1, 500) });
@@ -2135,11 +2573,13 @@ async function selectRecentMessageChats() {
 
   console.log(`\nSelect local Messages chats to sync\n`);
   console.log("Shepherd will only pull from the chats you select.");
+  console.log("Enter all to sync every current chat and keep watching future new chats.");
   for (let i = 0; i < chats.length; i++) {
     console.log(`${String(i + 1).padStart(2, " ")}. ${formatMessageChatOption(chats[i])}`);
   }
 
-  const answer = await prompt("\nEnter chat numbers to sync, separated by commas: ");
+  const answer = await prompt("\nEnter chat numbers to sync, separated by commas, or all: ");
+  if (String(answer ?? "").trim().toLowerCase() === "all") return [allMessagesChatsSelection()];
   const indexes = parseSelectionIndexes(answer, chats.length);
   if (indexes.length === 0) throw new Error("Select at least one Messages chat.");
   return indexes.map((idx) => chats[idx]);
@@ -2196,6 +2636,16 @@ async function selectChatsInBrowser(chats, opts = {}) {
             sendHtml(res, renderMessagesDonePage("Invalid selection session.", true), 403);
             return;
           }
+          if (form.get("allChats") === "1") {
+            if (!settled) res.once("finish", finishBrowserSelection);
+            sendHtml(res, renderMessagesDonePage("All current and future chats selected."));
+            if (!settled) {
+              settled = true;
+              clearTimeout(timeout);
+              resolve([allMessagesChatsSelection()]);
+            }
+            return;
+          }
           const selectedIds = form.getAll("chatId").filter(Boolean);
           const selectedSet = new Set(selectedIds);
           const selected = chats.filter((chat) => selectedSet.has(chat.chatId));
@@ -2385,6 +2835,31 @@ function renderMessagesSelectorPage(chats, token, error = "") {
       outline-offset: 1px;
     }
     .search::placeholder { color: var(--faint); }
+    .all-chats {
+      display: grid;
+      grid-template-columns: 20px minmax(0, 1fr);
+      gap: 12px;
+      align-items: start;
+      margin-top: 12px;
+      padding: 12px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      cursor: pointer;
+      background: #fbfbfa;
+    }
+    .all-chats:hover { border-color: var(--green); }
+    .all-title {
+      display: block;
+      font-size: 14px;
+      font-weight: 600;
+    }
+    .all-copy {
+      display: block;
+      margin-top: 2px;
+      color: var(--muted);
+      font-size: 12.5px;
+      line-height: 1.35;
+    }
     .error {
       margin: 0 0 12px;
       color: #9B1C1C;
@@ -2537,6 +3012,14 @@ function renderMessagesSelectorPage(chats, token, error = "") {
       <div class="panel">
         <div class="panel-head">
           <input class="search" id="search" type="search" placeholder="Search contacts or groups" autocomplete="off">
+          <label class="all-chats">
+            <input type="checkbox" id="all-chats" name="allChats" value="1">
+            <span class="box" aria-hidden="true"></span>
+            <span>
+              <span class="all-title">Sync all current and future chats</span>
+              <span class="all-copy">Backfill every current Messages chat and keep watching chats that appear later.</span>
+            </span>
+          </label>
         </div>
         ${error ? `<p class="error">${html(error)}</p>` : ""}
         <div class="list-head">
@@ -2562,6 +3045,7 @@ function renderMessagesSelectorPage(chats, token, error = "") {
     const selected = document.getElementById("selection-count");
     const form = document.querySelector("form");
     const checks = Array.from(document.querySelectorAll('input[name="chatId"]'));
+    const allChats = document.getElementById("all-chats");
 
     function updateRows() {
       const query = search.value.trim().toLowerCase();
@@ -2577,6 +3061,12 @@ function renderMessagesSelectorPage(chats, token, error = "") {
     }
 
     function updateSelected() {
+      if (allChats.checked) {
+        selected.textContent = "All current and future chats";
+        for (const check of checks) check.disabled = true;
+        return;
+      }
+      for (const check of checks) check.disabled = false;
       const count = checks.filter((check) => check.checked).length;
       selected.textContent = count + " selected";
     }
@@ -2587,6 +3077,7 @@ function renderMessagesSelectorPage(chats, token, error = "") {
       event.preventDefault();
       form.requestSubmit();
     });
+    allChats.addEventListener("change", updateSelected);
     for (const check of checks) check.addEventListener("change", updateSelected);
     updateRows();
     updateSelected();
@@ -2757,7 +3248,8 @@ async function listRecentMessageChats({ limit }) {
 
     const enriched = [];
     for (const chat of visible) {
-      enriched.push(await enrichMessageChat(sdk, chat, contactLookup));
+      const candidate = await enrichMessageChat(sdk, chat, contactLookup);
+      if (!messageChatTouchesShepherdAgent(candidate)) enriched.push(candidate);
     }
     return enriched;
   } finally {
@@ -2765,6 +3257,41 @@ async function listRecentMessageChats({ limit }) {
   }
 }
 
+async function loadSelectedMessageChatsForConfig(chatIds) {
+  const allowedChatIds = parseAllowedChatIds(chatIds);
+  if (allowedChatIds.length === 0 || selectedChatIdsIncludeAll(allowedChatIds)) return [];
+  if (platform() !== "darwin") return [];
+
+  const kit = await import("@photon-ai/imessage-kit");
+  const sdk = new kit.IMessageSDK({ debug: args.debug === true });
+  const contactLookup = buildContactLookup();
+  try {
+    const listedChats = typeof sdk.listChats === "function"
+      ? await sdk.listChats({ sortBy: "recent", limit: 5_000 }).catch(() => [])
+      : [];
+    const byId = new Map(listedChats
+      .filter((chat) => typeof chat?.chatId === "string")
+      .map((chat) => [chat.chatId, chat]));
+
+    const selected = [];
+    for (const chatId of allowedChatIds) {
+      const listed = byId.get(chatId);
+      const fallback = {
+        chatId,
+        kind: parseDmHandleFromChatId(chatId) ? "dm" : "group",
+        name: null,
+        service: null,
+        lastMessageAt: null,
+      };
+      const candidate = await enrichMessageChat(sdk, { ...fallback, ...listed, chatId }, contactLookup);
+      if (!messageChatTouchesShepherdAgent(candidate)) selected.push(candidate);
+    }
+    return selected;
+  } finally {
+    await sdk.close?.().catch(() => undefined);
+  }
+}
+
 async function enrichMessageChat(sdk, chat, contactLookup) {
   const recentMessages = await sdk.getMessages({ chatId: chat.chatId, limit: 30 }).catch(() => []);
   const participants = uniqueParticipants(recentMessages, contactLookup);
@@ -2795,7 +3322,7 @@ function uniqueParticipants(messages, contactLookup) {
   const participants = [];
   for (const msg of messages) {
     const handle = typeof msg.participant === "string" ? msg.participant.trim() : "";
-    if (!handle || contactLookup.isSelfHandle(handle)) continue;
+    if (!handle || contactLookup.isSelfHandle(handle) || isShepherdAgentMessageHandle(handle)) continue;
     const normalized = normalizeHandle(handle);
     if (seen.has(normalized)) continue;
     seen.add(normalized);
@@ -2825,6 +3352,21 @@ function publicMessageChat(chat) {
   };
 }
 
+function allMessagesChatsSelection() {
+  return {
+    chatId: ALL_MESSAGES_CHATS,
+    label: "All current and future chats",
+    kind: "all",
+    service: null,
+    lastMessageAt: null,
+    participants: [],
+  };
+}
+
+function selectedIncludesAllChats(chats) {
+  return Array.isArray(chats) && chats.some((chat) => chat?.chatId === ALL_MESSAGES_CHATS);
+}
+
 async function loadGroupChatNames(sdk, serializer) {
   if (typeof sdk.listChats !== "function") return;
   try {
@@ -2847,21 +3389,67 @@ function loadSelectedChatNames(selectedChats, serializer) {
   }
 }
 
-async function runMessagesBackfill(sdk, sender, serializer, days, allowedChatIds) {
-  console.log(`Running ${days == null ? "all-history" : `${days}-day`} Messages backfill for ${allowedChatIds.length} selected chat(s)`);
+function selectedChatContactSeedHandles(selectedChats, allowedChatIds) {
+  const handles = [];
+  for (const chatId of allowedChatIds ?? []) {
+    const dmHandle = parseDmHandleFromChatId(chatId);
+    if (dmHandle && !isShepherdAgentMessageHandle(dmHandle)) handles.push(dmHandle);
+  }
+  for (const chat of Array.isArray(selectedChats) ? selectedChats : []) {
+    for (const participant of Array.isArray(chat?.participants) ? chat.participants : []) {
+      if (
+        typeof participant?.handle === "string"
+        && participant.handle.trim()
+        && !isShepherdAgentMessageHandle(participant.handle)
+      ) {
+        handles.push(participant.handle);
+      }
+    }
+  }
+  return [...new Set(handles)];
+}
+
+async function runMessagesBackfill(sdk, sender, serializer, days, allowedChatIds, contactSync = null) {
+  const allChats = allowedChatIds == null;
+  console.log(allChats
+    ? `Running ${days == null ? "all-history" : `${days}-day`} Messages backfill for all current chats`
+    : `Running ${days == null ? "all-history" : `${days}-day`} Messages backfill for ${allowedChatIds.length} selected chat(s)`);
   const since = days == null ? null : new Date(Date.now() - days * 24 * 60 * 60 * 1000);
   const pageSize = 1000;
   let totalMessages = 0;
   let totalStored = 0;
 
+  if (allChats) {
+    let offset = 0;
+    while (true) {
+      const messages = await sdk.getMessages({ ...(since ? { since } : {}), limit: pageSize, offset });
+      if (!messages.length) break;
+      const filtered = messages.filter((msg) => !messageTouchesShepherdAgent(msg));
+
+      contactSync?.observeMessages(filtered);
+      totalMessages += filtered.length;
+      const result = await sender.send(filtered.map((msg) => serializer.serialize(msg)));
+      totalStored += result.stored;
+      saveMessagesWatermark(sender.userId, maxRowId(messages));
+
+      if (messages.length < pageSize) break;
+      offset += pageSize;
+    }
+
+    console.log(`Messages backfill complete: stored ${totalStored} of ${totalMessages}`);
+    return;
+  }
+
   for (const chatId of allowedChatIds) {
     let offset = 0;
     while (true) {
       const messages = await sdk.getMessages({ chatId, ...(since ? { since } : {}), limit: pageSize, offset });
       if (!messages.length) break;
+      const filtered = messages.filter((msg) => !messageTouchesShepherdAgent(msg));
 
-      totalMessages += messages.length;
-      const result = await sender.send(messages.map((msg) => serializer.serialize(msg)));
+      contactSync?.observeMessages(filtered);
+      totalMessages += filtered.length;
+      const result = await sender.send(filtered.map((msg) => serializer.serialize(msg)));
       totalStored += result.stored;
       saveMessagesWatermark(sender.userId, maxRowId(messages));
 
@@ -2873,24 +3461,35 @@ async function runMessagesBackfill(sdk, sender, serializer, days, allowedChatIds
   console.log(`Messages backfill complete: stored ${totalStored} of ${totalMessages}`);
 }
 
-async function gapFillFromWatermark(sdk, sender, serializer, userId, allowedChatIds) {
+async function gapFillFromWatermark(sdk, sender, serializer, userId, allowedChatIds, contactSync = null) {
+  const allChats = allowedChatIds == null;
   const lastWatermark = loadMessagesWatermark(userId);
   if (lastWatermark <= 0) return;
 
   const missed = [];
-  for (const chatId of allowedChatIds) {
-    missed.push(...await sdk.getMessages({ chatId, limit: 1000 }));
+  if (allChats) {
+    missed.push(...await sdk.getMessages({ limit: 5000 }));
+  } else {
+    for (const chatId of allowedChatIds) {
+      missed.push(...await sdk.getMessages({ chatId, limit: 1000 }));
+    }
   }
-  const newMessages = missed.filter((msg) => Number(msg.rowId) > lastWatermark && allowedChatIds.includes(msg.chatId));
+  const newMessages = missed.filter((msg) =>
+    Number(msg.rowId) > lastWatermark
+    && (allChats || allowedChatIds.includes(msg.chatId))
+    && !messageTouchesShepherdAgent(msg));
   if (newMessages.length === 0) return;
 
+  contactSync?.observeMessages(newMessages);
   const result = await sender.send(newMessages.map((msg) => serializer.serialize(msg)));
   if (result.stored > 0) saveMessagesWatermark(userId, maxRowId(newMessages));
   console.log(`Messages gap-fill complete: stored ${result.stored} of ${newMessages.length}`);
 }
 
-async function watchMessages(sdk, sender, serializer, userId, allowedChatIds) {
-  const allowed = new Set(allowedChatIds);
+async function watchMessages(sdk, sender, serializer, userId, allowedChatIds, opts = {}) {
+  const allChats = allowedChatIds == null;
+  const allowed = new Set(allowedChatIds ?? []);
+  const contactSync = opts.contactSync ?? null;
   let buffer = [];
   let timer = null;
 
@@ -2910,7 +3509,9 @@ async function watchMessages(sdk, sender, serializer, userId, allowedChatIds) {
   };
 
   const onMessage = (msg) => {
-    if (!msg.chatId || !allowed.has(msg.chatId)) return;
+    if (!msg.chatId || (!allChats && !allowed.has(msg.chatId))) return;
+    if (messageTouchesShepherdAgent(msg)) return;
+    contactSync?.observeMessages([msg]);
     buffer.push(msg);
     if (buffer.length >= MAX_BATCH_SIZE) {
       if (timer) clearTimeout(timer);
@@ -2927,7 +3528,9 @@ async function watchMessages(sdk, sender, serializer, userId, allowedChatIds) {
     onError: (err) => console.error("Messages watcher error:", safeError(err)),
   });
 
-  console.log("Watching for new Messages in selected chats");
+  console.log(allChats
+    ? "Watching for new Messages in all current and future chats"
+    : "Watching for new Messages in selected chats");
 
   await new Promise((resolve) => {
     let stopping = false;
@@ -2935,6 +3538,7 @@ async function watchMessages(sdk, sender, serializer, userId, allowedChatIds) {
       if (stopping) return;
       stopping = true;
       if (timer) clearTimeout(timer);
+      contactSync?.stop();
       await flush().catch(() => undefined);
       await sdk.close?.().catch(() => undefined);
       resolve();
@@ -2945,15 +3549,170 @@ async function watchMessages(sdk, sender, serializer, userId, allowedChatIds) {
   });
 }
 
-function createMessageSerializer(kit, contactLookup = emptyContactLookup()) {
-  const chatNames = new Map();
-  const isImageAttachment = kit.isImageAttachment ?? (() => false);
-  const isVideoAttachment = kit.isVideoAttachment ?? (() => false);
-  const isAudioAttachment = kit.isAudioAttachment ?? (() => false);
-
+function createMutableContactLookup(initial = emptyContactLookup()) {
+  let current = initial;
   return {
-    setChatName(chatId, name) {
-      chatNames.set(chatId, name);
+    replace(next) {
+      current = next ?? emptyContactLookup();
+    },
+    resolveName(handle) {
+      return current.resolveName(handle);
+    },
+    isSelfHandle(handle) {
+      return current.isSelfHandle(handle);
+    },
+    mappings() {
+      return contactMappingsFromLookup(current);
+    },
+  };
+}
+
+function startMessagesContactSync(sender, contactLookup, opts = {}) {
+  const syncAllContacts = opts.syncAllContacts === true;
+  const observedHandles = new Set();
+  for (const handle of opts.seedHandles ?? []) rememberObservedHandle(observedHandles, contactLookup, handle);
+
+  let previousSnapshot = new Map();
+  let syncTimer = null;
+  let contactsWatcher = null;
+  let fallbackInterval = null;
+  let syncing = false;
+  let pendingReason = null;
+  let stopped = false;
+
+  const visibleMappings = () => {
+    const mappings = contactLookup.mappings();
+    if (syncAllContacts) return mappings;
+    return mappings.filter((mapping) => handleCandidates(mapping.handle).some((candidate) => observedHandles.has(candidate)));
+  };
+
+  const syncNow = async ({ forceAll = false, reason = "manual" } = {}) => {
+    if (stopped) return { skipped: true, reason: "stopped" };
+    if (syncing) {
+      pendingReason = reason;
+      return { skipped: true, reason: "already_syncing" };
+    }
+
+    syncing = true;
+    try {
+      const nextLookup = buildContactLookup();
+      contactLookup.replace(nextLookup);
+      const mappings = visibleMappings();
+      const toSync = forceAll
+        ? mappings
+        : mappings.filter((mapping) => previousSnapshot.get(mapping.handle) !== mapping.name);
+
+      if (toSync.length === 0) {
+        previousSnapshot = snapshotContactMappings(mappings);
+        return { updated: 0, contactsProcessed: 0 };
+      }
+
+      const result = await sender.syncContacts(toSync);
+      previousSnapshot = snapshotContactMappings(mappings);
+      console.log(`[contacts] Synced ${toSync.length}/${mappings.length} Messages contact mappings (${reason}); updated ${result.updated ?? 0}`);
+      return result;
+    } finally {
+      syncing = false;
+      const queuedReason = pendingReason;
+      pendingReason = null;
+      if (queuedReason && !stopped) scheduleSync(queuedReason);
+    }
+  };
+
+  const scheduleSync = (reason) => {
+    if (stopped) return;
+    if (syncTimer) clearTimeout(syncTimer);
+    syncTimer = setTimeout(() => {
+      syncTimer = null;
+      syncNow({ reason }).catch((err) => console.error("Messages contact sync failed:", safeError(err)));
+    }, CONTACT_SYNC_DEBOUNCE_MS);
+  };
+
+  const observeMessages = (messages) => {
+    let changed = false;
+    for (const msg of messages ?? []) {
+      if (rememberObservedHandle(observedHandles, contactLookup, msg?.participant)) changed = true;
+      if (msg?.affectedParticipant) {
+        if (rememberObservedHandle(observedHandles, contactLookup, msg.affectedParticipant)) changed = true;
+      }
+    }
+    if (changed) scheduleSync("observed-message-handle");
+  };
+
+  const contactWatchPaths = addressBookWalPaths();
+  if (contactWatchPaths.length > 0) {
+    contactsWatcher = [];
+    for (const path of contactWatchPaths) {
+      try {
+        contactsWatcher.push(watch(path, () => scheduleSync("contacts-watch")));
+      } catch (err) {
+        console.warn(`Could not watch Contacts WAL ${path}: ${safeError(err)}`);
+      }
+    }
+    if (contactsWatcher.length > 0) {
+      console.log(`Watching ${contactsWatcher.length} Contacts database WAL file(s) for Messages name changes`);
+    } else {
+      console.warn("Contacts WAL files were found but could not be watched; Messages contact sync will use fallback polling only");
+    }
+  } else if (platform() === "darwin") {
+    console.warn("Contacts WAL not found; Messages contact sync will use fallback polling only");
+  }
+
+  fallbackInterval = setInterval(() => {
+    syncNow({ reason: "fallback" }).catch((err) => console.error("Messages contact fallback sync failed:", safeError(err)));
+  }, CONTACT_SYNC_FALLBACK_MS);
+
+  return {
+    observeMessages,
+    syncNow,
+    stop() {
+      stopped = true;
+      if (syncTimer) clearTimeout(syncTimer);
+      if (fallbackInterval) clearInterval(fallbackInterval);
+      if (contactsWatcher) {
+        for (const watcher of contactsWatcher) watcher.close();
+      }
+    },
+  };
+}
+
+function rememberObservedHandle(observedHandles, contactLookup, handle) {
+  const raw = typeof handle === "string" ? handle.trim() : "";
+  if (!raw || contactLookup.isSelfHandle(raw)) return false;
+  let changed = false;
+  for (const candidate of handleCandidates(raw)) {
+    if (!observedHandles.has(candidate)) {
+      observedHandles.add(candidate);
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+function contactMappingsFromLookup(lookup) {
+  const mappings = typeof lookup?.mappings === "function" ? lookup.mappings() : lookup?.mappings;
+  if (!Array.isArray(mappings)) return [];
+  return mappings.filter((mapping) =>
+    mapping
+    && typeof mapping.handle === "string"
+    && mapping.handle.trim()
+    && typeof mapping.name === "string"
+    && mapping.name.trim());
+}
+
+function snapshotContactMappings(mappings) {
+  return new Map(mappings.map((mapping) => [mapping.handle, mapping.name]));
+}
+
+function createMessageSerializer(kit, contactLookup = emptyContactLookup()) {
+  const chatNames = new Map();
+  const isImageAttachment = kit.isImageAttachment ?? (() => false);
+  const isVideoAttachment = kit.isVideoAttachment ?? (() => false);
+  const isAudioAttachment = kit.isAudioAttachment ?? (() => false);
+
+  return {
+    setChatName(chatId, name) {
+      chatNames.set(chatId, name);
     },
     serialize(msg) {
       const chatId = msg.chatId ?? "unknown";
@@ -3039,6 +3798,9 @@ function buildContactLookup(opts = {}) {
     isSelfHandle(handle) {
       return handleCandidates(handle).some((candidate) => selfHandles.has(candidate));
     },
+    mappings() {
+      return [...handleToName.entries()].map(([handle, name]) => ({ handle, name }));
+    },
   };
 }
 
@@ -3050,6 +3812,9 @@ function emptyContactLookup() {
     isSelfHandle() {
       return false;
     },
+    mappings() {
+      return [];
+    },
   };
 }
 
@@ -3146,6 +3911,15 @@ function addressBookDatabasePaths() {
   }
 }
 
+function addressBookWalPaths() {
+  if (platform() !== "darwin") return [];
+  const paths = new Set([CONTACTS_WAL_PATH]);
+  for (const dbPath of addressBookDatabasePaths()) {
+    paths.add(`${dbPath}-wal`);
+  }
+  return [...paths].filter((path) => existsSync(path));
+}
+
 function loadMyCard() {
   if (platform() !== "darwin") return null;
   const script = `
@@ -3260,6 +4034,40 @@ function parseDmHandleFromChatId(chatId) {
   return null;
 }
 
+function messageChatTouchesShepherdAgent(chat) {
+  if (isShepherdAgentMessageHandle(parseDmHandleFromChatId(chat?.chatId))) return true;
+  return Array.isArray(chat?.participants)
+    && chat.participants.some((participant) => isShepherdAgentMessageHandle(participant?.handle));
+}
+
+function messageTouchesShepherdAgent(msg) {
+  return isShepherdAgentMessageHandle(msg?.participant)
+    || isShepherdAgentMessageHandle(msg?.affectedParticipant)
+    || isShepherdAgentMessageHandle(parseDmHandleFromChatId(msg?.chatId));
+}
+
+function isShepherdAgentMessageHandle(handle) {
+  if (!SHEPHERD_OWNED_MESSAGE_HANDLES.length) return false;
+  const blocked = new Set(SHEPHERD_OWNED_MESSAGE_HANDLES.flatMap(handleCandidates));
+  return handleCandidates(handle).some((candidate) => blocked.has(candidate));
+}
+
+function parseMessageHandleList(value) {
+  return String(value ?? "")
+    .split(",")
+    .map((handle) => handle.trim())
+    .filter(Boolean);
+}
+
+function mergeShepherdOwnedMessageHandles(value) {
+  for (const handle of Array.isArray(value) ? value : parseMessageHandleList(value)) {
+    if (typeof handle !== "string" || !handle.trim()) continue;
+    if (!SHEPHERD_OWNED_MESSAGE_HANDLES.includes(handle.trim())) {
+      SHEPHERD_OWNED_MESSAGE_HANDLES.push(handle.trim());
+    }
+  }
+}
+
 function parseSelectionIndexes(answer, max) {
   const indexes = new Set();
   for (const part of String(answer ?? "").split(/[,\s]+/).map((value) => value.trim()).filter(Boolean)) {
@@ -3285,7 +4093,15 @@ function parseMessageChatIdsArg() {
 function parseAllowedChatIds(value) {
   if (!value) return [];
   const raw = Array.isArray(value) ? value : String(value).split(",");
-  return [...new Set(raw.map((chatId) => String(chatId).trim()).filter(Boolean))];
+  const values = raw.map((chatId) => String(chatId).trim()).filter(Boolean);
+  if (values.some((chatId) => chatId.toLowerCase() === "all" || chatId === ALL_MESSAGES_CHATS)) {
+    return [ALL_MESSAGES_CHATS];
+  }
+  return [...new Set(values)];
+}
+
+function selectedChatIdsIncludeAll(chatIds) {
+  return Array.isArray(chatIds) && chatIds.includes(ALL_MESSAGES_CHATS);
 }
 
 function html(value) {
@@ -3299,6 +4115,513 @@ function htmlAttr(value) {
   return html(value).replace(/"/g, "&quot;");
 }
 
+async function scanCodingSessions(config, previousState = { hashes: {} }) {
+  const probes = await probeCodingSessionPaths(config);
+  const errors = [];
+  const sessions = [];
+  const codexDirs = Array.isArray(config.codexDirs) ? config.codexDirs : [CODEX_SESSIONS_DIR, CODEX_ARCHIVED_SESSIONS_DIR];
+  const claudeDir = typeof config.claudeProjectsDir === "string" ? config.claudeProjectsDir : CLAUDE_PROJECTS_DIR;
+  const maxFiles = Math.max(1, Math.floor(Number(config.maxFilesPerProvider ?? 300)));
+
+  for (const dir of codexDirs) {
+    try {
+      const files = await recentJsonlFiles(dir, maxFiles);
+      for (const file of files) {
+        const parsed = await parseCodexSessionFile(file, config).catch((err) => {
+          errors.push({ provider: "codex", pathHash: hashString(file), error: safeError(err) });
+          return null;
+        });
+        if (parsed) sessions.push(parsed);
+      }
+    } catch (err) {
+      if (args.debug) errors.push({ provider: "codex", pathHash: hashString(dir), error: safeError(err) });
+    }
+  }
+
+  try {
+    const files = await recentJsonlFiles(claudeDir, maxFiles);
+    for (const file of files) {
+      const parsed = await parseClaudeSessionFile(file, config).catch((err) => {
+        errors.push({ provider: "claude", pathHash: hashString(file), error: safeError(err) });
+        return null;
+      });
+      if (parsed) sessions.push(parsed);
+    }
+  } catch (err) {
+    if (args.debug) errors.push({ provider: "claude", pathHash: hashString(claudeDir), error: safeError(err) });
+  }
+
+  return {
+    probes,
+    errors,
+    sessions: sessions
+      .sort((a, b) => String(b.lastUpdatedAt ?? "").localeCompare(String(a.lastUpdatedAt ?? "")))
+      .slice(0, maxFiles * 2),
+    previousState,
+  };
+}
+
+async function probeCodingSessionPaths(config) {
+  const probes = [];
+  const codexDirs = Array.isArray(config.codexDirs) ? config.codexDirs : [CODEX_SESSIONS_DIR, CODEX_ARCHIVED_SESSIONS_DIR];
+  for (const path of codexDirs) probes.push(await probePath("codex", path));
+  probes.push(await probePath("claude", typeof config.claudeProjectsDir === "string" ? config.claudeProjectsDir : CLAUDE_PROJECTS_DIR));
+  return probes;
+}
+
+async function probePath(provider, path) {
+  try {
+    await access(path, fsConstants.R_OK);
+    const info = await stat(path);
+    return { provider, path, readable: true, directory: info.isDirectory() };
+  } catch (err) {
+    return { provider, path, readable: false, reason: err?.code ?? safeError(err) };
+  }
+}
+
+async function recentJsonlFiles(root, limit) {
+  const files = [];
+  await walkJsonl(root, files, limit * 8);
+  return files
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .slice(0, limit)
+    .map((file) => file.path);
+}
+
+async function walkJsonl(dir, files, cap) {
+  if (files.length >= cap) return;
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (files.length >= cap) return;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walkJsonl(path, files, cap).catch(() => undefined);
+    } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+      const info = await stat(path).catch(() => null);
+      if (info) files.push({ path, mtimeMs: info.mtimeMs });
+    }
+  }
+}
+
+async function parseCodexSessionFile(path, config) {
+  const lines = await readJsonlRecords(path);
+  if (lines.length === 0) return null;
+  const payloads = lines.map((line) => line.payload && typeof line.payload === "object" ? line.payload : line);
+  const meta = payloads.find((payload) => payload && typeof payload === "object" && (payload.id || payload.started_at || payload.cwd)) ?? {};
+  const timestamps = lines.map((line) => isoDate(line.timestamp ?? line.payload?.timestamp ?? line.payload?.started_at)).filter(Boolean);
+  const cwd = firstString(payloads, ["cwd"]);
+  const repo = await repoMetadata(cwd);
+  const actor = await actorMetadata(cwd, config);
+  const userTexts = extractTextValues(payloads, ["text", "query"]).filter((text) => text.length > 0);
+  const summaries = extractTextValues(payloads, ["summary", "formatted_output"]).filter((text) => text.length > 0);
+  const commands = extractCodexCommands(payloads);
+  const session = {
+    provider: "codex",
+    sessionId: cleanSessionId(String(meta.id ?? basename(path, ".jsonl"))),
+    startedAt: minIso(timestamps) ?? isoDate(meta.started_at),
+    endedAt: maxIso(timestamps),
+    lastUpdatedAt: maxIso(timestamps) ?? new Date().toISOString(),
+    status: sessionStatus(maxIso(timestamps)),
+    actor,
+    repo,
+    cwdHash: cwd ? hashString(cwd) : null,
+    cwdBasename: cwd ? basename(cwd) : null,
+    title: redactText(firstUseful(userTexts) ?? firstUseful(summaries) ?? basename(path, ".jsonl"), 180),
+    goal: redactText(firstUseful(userTexts), 600),
+    summary: buildLocalSessionSummary("Codex", userTexts, summaries, commands),
+    decisions: [],
+    filesTouched: inferFilesTouched([...userTexts, ...summaries, ...commands.map((command) => command.command)]),
+    commands,
+    verification: inferVerification(commands),
+    errors: inferErrors(commands, summaries),
+    followUps: inferFollowUps([...userTexts, ...summaries]),
+    omittedCounts: { rawLines: lines.length, uploadedRawTranscriptLines: 0 },
+    sourcePathHash: hashString(path),
+  };
+  session.contentHash = hashObject(session);
+  return session;
+}
+
+async function parseClaudeSessionFile(path, config) {
+  const lines = await readJsonlRecords(path);
+  if (lines.length === 0) return null;
+  const timestamps = lines.map((line) => isoDate(line.timestamp)).filter(Boolean);
+  const cwd = firstString(lines, ["cwd"]);
+  const repo = await repoMetadata(cwd);
+  const actor = await actorMetadata(cwd, config);
+  const sessionId = firstString(lines, ["sessionId"]) ?? basename(path, ".jsonl");
+  const title = firstString(lines, ["aiTitle", "lastPrompt", "slug"]) ?? firstMessageText(lines);
+  const userTexts = claudeTextValues(lines, "user");
+  const assistantTexts = claudeTextValues(lines, "assistant");
+  const commands = extractClaudeCommands(lines);
+  const session = {
+    provider: "claude",
+    sessionId: cleanSessionId(sessionId),
+    startedAt: minIso(timestamps),
+    endedAt: maxIso(timestamps),
+    lastUpdatedAt: maxIso(timestamps) ?? new Date().toISOString(),
+    status: sessionStatus(maxIso(timestamps)),
+    actor,
+    repo: {
+      ...repo,
+      branch: repo.branch ?? firstString(lines, ["gitBranch"]),
+    },
+    cwdHash: cwd ? hashString(cwd) : null,
+    cwdBasename: cwd ? basename(cwd) : null,
+    title: redactText(title, 180),
+    goal: redactText(firstUseful(userTexts), 600),
+    summary: buildLocalSessionSummary("Claude Code", userTexts, assistantTexts, commands),
+    decisions: [],
+    filesTouched: inferFilesTouched([...userTexts, ...assistantTexts, ...commands.map((command) => command.command)]),
+    commands,
+    verification: inferVerification(commands),
+    errors: inferErrors(commands, assistantTexts),
+    followUps: inferFollowUps([...userTexts, ...assistantTexts]),
+    omittedCounts: { rawLines: lines.length, uploadedRawTranscriptLines: 0 },
+    sourcePathHash: hashString(path),
+  };
+  session.contentHash = hashObject(session);
+  return session;
+}
+
+async function readJsonlRecords(path) {
+  const raw = await readFile(path, "utf8");
+  return raw
+    .split("\n")
+    .filter((line) => line.trim())
+    .slice(-3000)
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+}
+
+function extractCodexCommands(payloads) {
+  return payloads.flatMap((payload) => {
+    if (!payload || typeof payload !== "object") return [];
+    const command = payload.command ?? payload.parsed_cmd?.join?.(" ") ?? null;
+    if (typeof command !== "string" || !command.trim()) return [];
+    return [{
+      command: redactText(command, 600),
+      exitCode: typeof payload.exit_code === "number" ? payload.exit_code : null,
+      summary: payload.stdout || payload.stderr
+        ? redactText(String(payload.stderr || payload.stdout).split("\n").find(Boolean) ?? "", 240)
+        : null,
+    }];
+  }).slice(-100);
+}
+
+function extractClaudeCommands(lines) {
+  const commands = [];
+  for (const line of lines) {
+    const text = JSON.stringify(line.toolUseResult ?? line.message?.content ?? "");
+    const bashMatch = text.match(/(?:"command"|"input")\s*:\s*"([^"]{2,500})"/);
+    if (bashMatch && /\b(?:git|npm|pnpm|yarn|bun|pytest|vitest|cargo|go|python|node|tsc|ruff|eslint|make)\b/.test(bashMatch[1])) {
+      commands.push({ command: redactText(unescapeJsonString(bashMatch[1]), 600), exitCode: null, summary: null });
+    }
+  }
+  return commands.slice(-100);
+}
+
+async function repoMetadata(cwd) {
+  const base = { fullName: null, remote: null, branch: null, commit: null };
+  if (!cwd) return base;
+  const remote = await gitValue(cwd, ["config", "--get", "remote.origin.url"]);
+  const branch = await gitValue(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const commit = await gitValue(cwd, ["rev-parse", "--short", "HEAD"]);
+  return {
+    fullName: repoFullNameFromRemote(remote),
+    remote: remote ? redactCredentialUrl(remote) : null,
+    branch,
+    commit,
+  };
+}
+
+async function actorMetadata(cwd, config) {
+  const email = config.actorEmail ?? await gitValue(cwd, ["config", "user.email"]) ?? await gitValue(null, ["config", "--global", "user.email"]);
+  const name = config.actorName ?? await gitValue(cwd, ["config", "user.name"]) ?? await gitValue(null, ["config", "--global", "user.name"]);
+  return { email: email ?? null, name: name ?? null };
+}
+
+async function gitValue(cwd, argv) {
+  return new Promise((resolve) => {
+    execFile("git", argv, { cwd: cwd || undefined, timeout: 2000, windowsHide: true }, (error, stdout) => {
+      if (error) resolve(null);
+      else resolve(String(stdout).trim() || null);
+    });
+  });
+}
+
+function buildLocalSessionSummary(provider, userTexts, assistantTexts, commands) {
+  const primary = firstUseful([...userTexts, ...assistantTexts]);
+  const commandSummary = commands.length ? ` Commands included: ${commands.slice(-5).map((command) => command.command).join("; ")}.` : "";
+  return redactText(`${provider} session${primary ? `: ${primary}` : " synced."}${commandSummary}`, 1200);
+}
+
+function firstUseful(values) {
+  return values.find((value) => value && value.trim().length > 8) ?? null;
+}
+
+function firstString(records, keys) {
+  for (const record of records) {
+    if (!record || typeof record !== "object") continue;
+    for (const key of keys) {
+      const value = record[key];
+      if (typeof value === "string" && value.trim()) return value.trim();
+    }
+  }
+  return null;
+}
+
+function extractTextValues(records, keys) {
+  const values = [];
+  for (const record of records) {
+    if (!record || typeof record !== "object") continue;
+    for (const key of keys) {
+      const value = record[key];
+      if (typeof value === "string" && value.trim()) values.push(redactText(value, 1200));
+    }
+  }
+  return values;
+}
+
+function claudeTextValues(records, role) {
+  const values = [];
+  for (const record of records) {
+    const message = record?.message;
+    if (!message || typeof message !== "object" || message.role !== role) continue;
+    const content = message.content;
+    if (typeof content === "string") values.push(redactText(content, 1200));
+    if (Array.isArray(content)) {
+      for (const item of content) {
+        if (item?.type === "text" && typeof item.text === "string") values.push(redactText(item.text, 1200));
+      }
+    }
+  }
+  return values;
+}
+
+function firstMessageText(records) {
+  return firstUseful(claudeTextValues(records, "user")) ?? firstUseful(claudeTextValues(records, "assistant"));
+}
+
+function inferFilesTouched(values) {
+  const matches = new Set();
+  const fileRe = /\b(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\.(?:ts|tsx|js|jsx|py|rs|go|swift|kt|java|json|md|sql|css|html|yml|yaml|toml)\b/g;
+  for (const value of values) {
+    for (const match of String(value ?? "").matchAll(fileRe)) matches.add(match[0]);
+  }
+  return [...matches].slice(0, 200);
+}
+
+function inferVerification(commands) {
+  return commands
+    .filter((command) => /\b(?:test|vitest|jest|pytest|tsc|lint|eslint|build|cargo test|go test)\b/i.test(command.command))
+    .map((command) => `${command.command}${command.exitCode == null ? "" : ` exited ${command.exitCode}`}`)
+    .slice(0, 30);
+}
+
+function inferErrors(commands, texts) {
+  const errors = [];
+  for (const command of commands) {
+    if (typeof command.exitCode === "number" && command.exitCode !== 0) errors.push(`${command.command} exited ${command.exitCode}`);
+  }
+  for (const text of texts) {
+    if (/\b(?:error|failed|failing|blocked|exception)\b/i.test(text)) errors.push(redactText(text, 280));
+  }
+  return [...new Set(errors)].slice(0, 30);
+}
+
+function inferFollowUps(texts) {
+  return texts
+    .filter((text) => /\b(?:todo|follow up|next|later|needs?|remaining)\b/i.test(text))
+    .map((text) => redactText(text, 280))
+    .slice(0, 30);
+}
+
+function sessionStatus(lastUpdatedAt) {
+  if (!lastUpdatedAt) return "unknown";
+  return Date.now() - Date.parse(lastUpdatedAt) < 5 * 60_000 ? "active" : "settled";
+}
+
+function minIso(values) {
+  return values.length ? values.sort()[0] : null;
+}
+
+function maxIso(values) {
+  return values.length ? values.sort().at(-1) : null;
+}
+
+function cleanSessionId(value) {
+  return String(value ?? "").replace(/[^a-zA-Z0-9_.:-]/g, "-").slice(0, 200) || hashString(value).slice(0, 16);
+}
+
+function repoFullNameFromRemote(remote) {
+  if (!remote) return null;
+  const match = String(remote).match(/[:/]([^/:]+\/[^/.]+)(?:\.git)?$/);
+  return match?.[1] ?? null;
+}
+
+function redactCredentialUrl(value) {
+  return String(value).replace(/:\/\/[^/@]+@/g, "://[redacted]@");
+}
+
+function redactText(value, maxLength = 1000) {
+  return String(value ?? "")
+    .replace(/-----BEGIN [^-]+PRIVATE KEY-----[\s\S]*?-----END [^-]+PRIVATE KEY-----/g, "[redacted-private-key]")
+    .replace(/\b(?:sk|pk|rk|ghp|github_pat|xox[baprs])_[A-Za-z0-9_=-]{12,}\b/g, "[redacted-token]")
+    .replace(/\b[A-Za-z0-9._%+-]+:[A-Za-z0-9._%+-]+@/g, "[redacted-credentials]@")
+    .replace(/\b(?:authorization|x-api-key|api[_-]?key|token|secret|password)\s*[:=]\s*['\"]?[^'\"\s]+/gi, "$1=[redacted]")
+    .replace(/(OPENAI_API_KEY|FIREWORKS_API_KEY|ANTHROPIC_API_KEY|DATABASE_URL|REDIS_URL)=\S+/g, "$1=[redacted]")
+    .replace(new RegExp(homedir().replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"), "~")
+    .slice(0, maxLength);
+}
+
+function unescapeJsonString(value) {
+  try {
+    return JSON.parse(`"${value.replace(/"/g, '\\"')}"`);
+  } catch {
+    return value;
+  }
+}
+
+function hashString(value) {
+  return createHash("sha256").update(String(value ?? "")).digest("hex");
+}
+
+function hashObject(value) {
+  return hashString(JSON.stringify(value));
+}
+
+function readCodingSessionsState(path) {
+  const value = readJsonOptional(path);
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? { hashes: value.hashes && typeof value.hashes === "object" ? value.hashes : {} }
+    : { hashes: {} };
+}
+
+function codingSessionsStateFile(userId) {
+  const path = join(homedir(), ".shepherd", "coding-sessions", `${safeFileId(userId)}-state.json`);
+  mkdirSync(dirname(path), { recursive: true });
+  return path;
+}
+
+function codingSessionsStatusFile(userId) {
+  const path = join(homedir(), ".shepherd", "coding-sessions", `${safeFileId(userId)}-status.json`);
+  mkdirSync(dirname(path), { recursive: true });
+  return path;
+}
+
+async function latestCodingSessionsConfigPath() {
+  const dir = join(homedir(), ".shepherd", "coding-sessions");
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json") || entry.name.includes("-state") || entry.name.includes("-status") || entry.name.includes("-queue")) continue;
+      const path = join(dir, entry.name);
+      const info = await stat(path).catch(() => null);
+      if (info) files.push({ path, mtimeMs: info.mtimeMs });
+    }
+    return files.sort((a, b) => b.mtimeMs - a.mtimeMs)[0]?.path ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function productionOnboardingStatusForCodingSessions(config) {
+  if (!config?.userId || !config?.apiUrl) return null;
+  const local = await readOptionalAgentState().catch(() => null);
+  if (!local?.sessionToken || local.sessionId !== config.userId) return null;
+  return getJson(
+    `${trimTrailingSlash(config.apiUrl)}/onboarding/raw/session/${encodeURIComponent(config.userId)}/status`,
+    { token: local.sessionToken },
+  );
+}
+
+function readJsonOptional(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+class CodingSessionsBatchSender {
+  constructor(apiUrl, agentToken, userId) {
+    this.apiUrl = trimTrailingSlash(apiUrl);
+    this.agentToken = agentToken;
+    this.userId = userId;
+    this.queueFile = join(homedir(), ".shepherd", "coding-sessions", `${safeFileId(userId)}-queue.json`);
+  }
+
+  async send(sessions) {
+    const queued = this.loadQueue();
+    const all = [...queued, ...sessions];
+    if (!all.length) return { stored: 0, updated: 0, skipped: 0 };
+
+    let totalStored = 0;
+    let totalUpdated = 0;
+    let totalSkipped = 0;
+
+    for (let i = 0; i < all.length; i += MAX_BATCH_SIZE) {
+      const batch = all.slice(i, i + MAX_BATCH_SIZE);
+      try {
+        const result = await this.postBatch(batch);
+        totalStored += result.stored ?? 0;
+        totalUpdated += result.updated ?? 0;
+        totalSkipped += result.skipped ?? 0;
+      } catch (err) {
+        this.saveQueue(all.slice(i));
+        console.error("Coding sessions batch send failed:", safeError(err));
+        return { stored: totalStored, updated: totalUpdated, skipped: totalSkipped };
+      }
+    }
+
+    this.clearQueue();
+    return { stored: totalStored, updated: totalUpdated, skipped: totalSkipped };
+  }
+
+  async postBatch(sessions) {
+    const res = await fetch(`${this.apiUrl}/api/coding-sessions/ingest`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.agentToken,
+      },
+      body: JSON.stringify({ userId: this.userId, sessions }),
+    });
+
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error(json.error ?? `Coding sessions ingest failed (${res.status})`);
+    return json;
+  }
+
+  loadQueue() {
+    try {
+      return JSON.parse(readFileSync(this.queueFile, "utf8"));
+    } catch {
+      return [];
+    }
+  }
+
+  saveQueue(sessions) {
+    mkdirSync(dirname(this.queueFile), { recursive: true });
+    writeFileSync(this.queueFile, JSON.stringify(sessions.slice(-MAX_QUEUE_MESSAGES)), { mode: 0o600 });
+  }
+
+  clearQueue() {
+    try {
+      unlinkSync(this.queueFile);
+    } catch {
+      // Queue is already empty.
+    }
+  }
+}
+
 class MessagesBatchSender {
   constructor(apiUrl, agentToken, userId) {
     this.apiUrl = trimTrailingSlash(apiUrl);
@@ -3347,6 +4670,21 @@ class MessagesBatchSender {
     return json;
   }
 
+  async syncContacts(contacts) {
+    const res = await fetch(`${this.apiUrl}/api/imessage/ingest/sync-contacts`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.agentToken,
+      },
+      body: JSON.stringify({ userId: this.userId, contacts }),
+    });
+
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error(json.error ?? `Messages contact sync failed (${res.status})`);
+    return json;
+  }
+
   loadQueue() {
     try {
       return JSON.parse(readFileSync(this.queueFile, "utf8"));