birdclaw 0.5.1 → 0.7.0

package/src/cli.ts

@@ -10,6 +10,9 @@ import { findArchives } from "#/lib/archive-finder";
 import {
 	ARCHIVE_IMPORT_SLICES,
 	type ArchiveImportSlice,
+	type ImportProgressEvent,
+	type ImportProgressSlice,
+	type ImportWritePhase,
 	importArchive,
 } from "#/lib/archive-import";
 import {
@@ -17,6 +20,11 @@ import {
 	syncAuthoredTweets,
 	type AuthoredSyncMode,
 } from "#/lib/authored-live";
+import {
+	installAccountSyncLaunchAgent,
+	parseAccountSyncSteps,
+	runAccountSyncJob,
+} from "#/lib/account-sync-job";
 import {
 	exportBackup,
 	importBackup,
@@ -29,24 +37,40 @@ import {
 	installBookmarkSyncLaunchAgent,
 	runBookmarkSyncJob,
 } from "#/lib/bookmark-sync-job";
+import { runDirectMessageRequestMutationViaBird } from "#/lib/bird";
 import { importBlocklist } from "#/lib/blocklist";
 import {
 	type ActionsTransport,
 	ensureBirdclawDirs,
 	getBirdclawPaths,
 	resolveMentionsDataSource,
+	setActionsTransport,
 } from "#/lib/config";
-import { syncDirectMessagesViaCachedBird } from "#/lib/dms-live";
+import { closeDatabase } from "#/lib/db";
+import {
+	type DirectMessagesSyncMode,
+	syncDirectMessagesViaCachedBird,
+} from "#/lib/dms-live";
 import { listInboxItems, scoreInbox } from "#/lib/inbox";
 import { backfillLinkIndex, searchLinks } from "#/lib/link-index";
 import { fetchTweetMedia, formatMediaFetchResult } from "#/lib/media-fetch";
 import { syncMentionThreads } from "#/lib/mention-threads-live";
 import { exportMentionItems } from "#/lib/mentions-export";
 import {
+	exportMentionsViaCachedAuto,
 	exportMentionsViaCachedBird,
 	exportMentionsViaCachedXurl,
 	syncMentions,
 } from "#/lib/mentions-live";
+import {
+	streamPeriodDigest,
+	type PeriodDigestOptions,
+	type PeriodDigestPreset,
+} from "#/lib/period-digest";
+import {
+	streamProfileAnalysis,
+	type ProfileAnalysisOptions,
+} from "#/lib/profile-analysis";
 import {
 	getFollowGraphSummary,
 	listFollowEvents,
@@ -61,6 +85,12 @@ import { resolveProfilesForIds } from "#/lib/profile-resolver";
 import { inspectProfileReplies } from "#/lib/profile-replies";
 import { runResearchMode } from "#/lib/research";
 import {
+	streamSearchDiscussion,
+	type SearchDiscussionOptions,
+	type SearchDiscussionSource,
+} from "#/lib/search-discussion";
+import {
+	applyDmRequestMutationToLocalStore,
 	createDmReply,
 	createPost,
 	createTweetReply,
@@ -98,6 +128,71 @@ function errorMessage(error: unknown) {
 	return error instanceof Error ? error.message : String(error);
 }
 
+const IMPORT_SLICE_LABELS: Record<ImportProgressSlice, string> = {
+	tweets: "tweets",
+	noteTweets: "note tweets",
+	directMessages: "direct messages",
+	likes: "likes",
+	bookmarks: "bookmarks",
+	media: "media files",
+	followers: "followers",
+	following: "following",
+};
+
+const IMPORT_WRITE_LABELS: Record<ImportWritePhase, string> = {
+	profiles: "profiles",
+	tweets: "tweets",
+	collections: "likes+bookmarks",
+	dmMessages: "DM messages",
+};
+
+function logImportProgress(event: ImportProgressEvent) {
+	switch (event.kind) {
+		case "scanned":
+			process.stderr.write(
+				`Scanning archive… ${String(event.entryCount)} entries\n`,
+			);
+			return;
+		case "slice-start":
+			if (event.slice === "media") {
+				process.stderr.write("Indexing media files…\n");
+				return;
+			}
+			process.stderr.write(
+				`Parsing ${IMPORT_SLICE_LABELS[event.slice]}… (${String(event.files)} file${event.files === 1 ? "" : "s"})\n`,
+			);
+			return;
+		case "slice-file":
+			if (event.files > 1) {
+				process.stderr.write(
+					`  ${IMPORT_SLICE_LABELS[event.slice]} ${String(event.processed)}/${String(event.files)}\n`,
+				);
+			}
+			return;
+		case "slice-done":
+			process.stderr.write(
+				`  ${IMPORT_SLICE_LABELS[event.slice]}: ${event.count.toLocaleString()}\n`,
+			);
+			return;
+		case "writing":
+			process.stderr.write("Writing to database…\n");
+			return;
+		case "write-start":
+			process.stderr.write(
+				`Writing ${IMPORT_WRITE_LABELS[event.phase]}… (${event.total.toLocaleString()})\n`,
+			);
+			return;
+		case "write-progress":
+			process.stderr.write(
+				`  ${IMPORT_WRITE_LABELS[event.phase]} ${event.processed.toLocaleString()}/${event.total.toLocaleString()}\n`,
+			);
+			return;
+		case "done":
+			process.stderr.write("Import complete.\n");
+			return;
+	}
+}
+
 function formatLinkSearchItems(items: ReturnType<typeof searchLinks>) {
 	return items
 		.map((item) => {
@@ -154,6 +249,49 @@ function parsePositiveIntegerOption(value: string | undefined, option: string) {
 	return parsed;
 }
 
+function parseDmInboxOption(
+	value: string | undefined,
+): "all" | "accepted" | "requests" | undefined {
+	const normalized = (value ?? "all").trim().toLowerCase();
+	if (
+		normalized === "all" ||
+		normalized === "accepted" ||
+		normalized === "requests"
+	) {
+		return normalized;
+	}
+	if (normalized === "request") {
+		return "requests";
+	}
+	printError("--inbox must be all, accepted, or requests");
+	process.exitCode = 1;
+	return undefined;
+}
+
+function parseDmSyncModeOption(
+	value: string | undefined,
+): DirectMessagesSyncMode | undefined {
+	const normalized = (value ?? "bird").trim().toLowerCase();
+	if (normalized === "auto" || normalized === "bird" || normalized === "xurl") {
+		return normalized;
+	}
+	printError("--mode must be auto, bird, or xurl");
+	process.exitCode = 1;
+	return undefined;
+}
+
+function parseDigestLiveModeOption(
+	value: string | undefined,
+): PeriodDigestOptions["liveSyncMode"] {
+	const normalized = (value ?? "xurl").trim().toLowerCase();
+	if (normalized === "auto" || normalized === "bird" || normalized === "xurl") {
+		return normalized;
+	}
+	printError("--live-mode must be auto, bird, or xurl");
+	process.exitCode = 1;
+	return undefined;
+}
+
 function parseArchiveImportSelect(value: string | undefined) {
 	if (value === undefined) {
 		return undefined;
@@ -209,6 +347,316 @@ function resolveActionOptions(options: { transport?: string }) {
 	};
 }
 
+function parseActionsTransport(value: string | undefined) {
+	const normalized = value?.trim().toLowerCase();
+	if (normalized === "auto" || normalized === "bird" || normalized === "xurl") {
+		return normalized;
+	}
+	printError("transport must be auto, bird, or xurl");
+	process.exitCode = 1;
+	return undefined;
+}
+
+function parseDigestPeriod(value: string | undefined): PeriodDigestPreset {
+	const normalized = value?.trim().toLowerCase();
+	if (normalized === "yesterday") return "yesterday";
+	if (normalized === "24h" || normalized === "day") return "24h";
+	if (normalized === "week" || normalized === "7d") return "week";
+	return "today";
+}
+
+function buildDigestOptions(
+	period: string | undefined,
+	options: {
+		account?: string;
+		includeDms?: boolean;
+		model?: string;
+		refresh?: boolean;
+		since?: string;
+		until?: string;
+		maxTweets?: string;
+		maxLinks?: string;
+		liveSync?: boolean;
+		liveMode?: string;
+	},
+): PeriodDigestOptions | null {
+	const maxTweets = parseNonNegativeIntegerOption(
+		options.maxTweets,
+		"--max-tweets",
+	);
+	if (options.maxTweets !== undefined && maxTweets === undefined) {
+		return null;
+	}
+	const maxLinks = parseNonNegativeIntegerOption(
+		options.maxLinks,
+		"--max-links",
+	);
+	if (options.maxLinks !== undefined && maxLinks === undefined) {
+		return null;
+	}
+	const liveSyncMode = parseDigestLiveModeOption(options.liveMode);
+	if (liveSyncMode === undefined) {
+		return null;
+	}
+	return {
+		period: parseDigestPeriod(period),
+		since: options.since,
+		until: options.until,
+		account: options.account,
+		includeDms: Boolean(options.includeDms),
+		refresh: Boolean(options.refresh),
+		model: options.model,
+		maxTweets,
+		maxLinks,
+		liveSync: options.liveSync !== false,
+		liveSyncMode,
+	};
+}
+
+function runDigestCli(options: PeriodDigestOptions) {
+	const asJson = Boolean(program.opts().json);
+	return streamPeriodDigest(options, {
+		onDelta: asJson
+			? undefined
+			: (delta) => {
+					process.stdout.write(delta);
+				},
+	}).then((result) => {
+		if (asJson) {
+			print(result, true);
+			return;
+		}
+		if (!result.markdown.endsWith("\n")) {
+			process.stdout.write("\n");
+		}
+	});
+}
+
+function parseSearchDiscussionSource(
+	value: string | undefined,
+): SearchDiscussionSource | undefined {
+	const normalized = (value ?? "all").trim().toLowerCase();
+	if (
+		normalized === "all" ||
+		normalized === "home" ||
+		normalized === "mentions" ||
+		normalized === "authored" ||
+		normalized === "search" ||
+		normalized === "likes" ||
+		normalized === "bookmarks"
+	) {
+		return normalized;
+	}
+	printError(
+		"--source must be all, search, home, mentions, authored, likes, or bookmarks",
+	);
+	process.exitCode = 1;
+	return undefined;
+}
+
+function parseTweetSearchMode(value: string | undefined) {
+	const normalized = (value ?? "auto").trim().toLowerCase();
+	if (
+		normalized === "auto" ||
+		normalized === "bird" ||
+		normalized === "xurl" ||
+		normalized === "local"
+	) {
+		return normalized;
+	}
+	printError("--mode must be auto, bird, xurl, or local");
+	process.exitCode = 1;
+	return undefined;
+}
+
+function buildSearchDiscussionOptions(
+	query: string,
+	options: {
+		account?: string;
+		source?: string;
+		includeDms?: boolean;
+		since?: string;
+		until?: string;
+		question?: string;
+		originalsOnly?: boolean;
+		hideLowQuality?: boolean;
+		mode?: string;
+		model?: string;
+		refresh?: boolean;
+		limit?: string;
+		maxPages?: string;
+	},
+): SearchDiscussionOptions | null {
+	const source = parseSearchDiscussionSource(options.source);
+	if (!source) return null;
+	const mode = parseTweetSearchMode(options.mode);
+	if (!mode) return null;
+	const limit = parsePositiveIntegerOption(options.limit, "--limit");
+	if (options.limit !== undefined && limit === undefined) {
+		return null;
+	}
+	const maxPages = parsePositiveIntegerOption(options.maxPages, "--max-pages");
+	if (options.maxPages !== undefined && maxPages === undefined) {
+		return null;
+	}
+	return {
+		query,
+		account: options.account,
+		source,
+		includeDms: Boolean(options.includeDms),
+		since: options.since,
+		until: options.until,
+		question: options.question,
+		originalsOnly: Boolean(options.originalsOnly),
+		hideLowQuality: Boolean(options.hideLowQuality),
+		mode,
+		model: options.model,
+		refresh: Boolean(options.refresh),
+		limit,
+		maxPages,
+	};
+}
+
+function runSearchDiscussionCli(options: SearchDiscussionOptions) {
+	const asJson = Boolean(program.opts().json);
+	return streamSearchDiscussion(options, {
+		onDelta: asJson
+			? undefined
+			: (delta) => {
+					process.stdout.write(delta);
+				},
+	}).then((result) => {
+		if (asJson) {
+			print(result, true);
+			return;
+		}
+		if (!result.markdown.endsWith("\n")) {
+			process.stdout.write("\n");
+		}
+	});
+}
+
+function buildProfileAnalysisOptions(
+	handle: string,
+	options: {
+		account?: string;
+		model?: string;
+		refresh?: boolean;
+		maxTweets?: string;
+		maxPages?: string;
+		maxConversations?: string;
+		maxConversationPages?: string;
+		conversationDelayMs?: string;
+		rateLimitRetryMs?: string;
+		rateLimitRetries?: string;
+	},
+): ProfileAnalysisOptions | null {
+	const maxTweets = parsePositiveIntegerOption(
+		options.maxTweets,
+		"--max-tweets",
+	);
+	if (options.maxTweets !== undefined && maxTweets === undefined) {
+		return null;
+	}
+	const maxPages = parsePositiveIntegerOption(options.maxPages, "--max-pages");
+	if (options.maxPages !== undefined && maxPages === undefined) {
+		return null;
+	}
+	const maxConversations = parsePositiveIntegerOption(
+		options.maxConversations,
+		"--max-conversations",
+	);
+	if (
+		options.maxConversations !== undefined &&
+		maxConversations === undefined
+	) {
+		return null;
+	}
+	const maxConversationPages = parsePositiveIntegerOption(
+		options.maxConversationPages,
+		"--max-conversation-pages",
+	);
+	if (
+		options.maxConversationPages !== undefined &&
+		maxConversationPages === undefined
+	) {
+		return null;
+	}
+	const conversationDelayMs = parseNonNegativeIntegerOption(
+		options.conversationDelayMs,
+		"--conversation-delay-ms",
+	);
+	if (
+		options.conversationDelayMs !== undefined &&
+		conversationDelayMs === undefined
+	) {
+		return null;
+	}
+	const rateLimitRetryMs = parseNonNegativeIntegerOption(
+		options.rateLimitRetryMs,
+		"--rate-limit-retry-ms",
+	);
+	if (
+		options.rateLimitRetryMs !== undefined &&
+		rateLimitRetryMs === undefined
+	) {
+		return null;
+	}
+	const rateLimitMaxRetries = parseNonNegativeIntegerOption(
+		options.rateLimitRetries,
+		"--rate-limit-retries",
+	);
+	if (
+		options.rateLimitRetries !== undefined &&
+		rateLimitMaxRetries === undefined
+	) {
+		return null;
+	}
+	return {
+		handle,
+		account: options.account,
+		model: options.model,
+		refresh: Boolean(options.refresh),
+		maxTweets,
+		maxPages,
+		maxConversations,
+		maxConversationPages,
+		conversationDelayMs,
+		rateLimitRetryMs,
+		rateLimitMaxRetries,
+	};
+}
+
+function runProfileAnalysisCli(options: ProfileAnalysisOptions) {
+	const asJson = Boolean(program.opts().json);
+	return streamProfileAnalysis(options, {
+		onDelta: asJson
+			? undefined
+			: (delta) => {
+					process.stdout.write(delta);
+				},
+		onEvent: asJson
+			? undefined
+			: (event) => {
+					if (event.type === "status") {
+						process.stderr.write(
+							event.detail
+								? `${event.label}: ${event.detail}\n`
+								: `${event.label}\n`,
+						);
+					}
+				},
+	}).then((result) => {
+		if (asJson) {
+			print(result, true);
+			return;
+		}
+		if (!result.markdown.endsWith("\n")) {
+			process.stdout.write("\n");
+		}
+	});
+}
+
 async function enrichDmItems(
 	query: Parameters<typeof listDmConversations>[0],
 	options: {
@@ -260,14 +708,28 @@ async function enrichDmItems(
 }
 
 async function autoUpdateBeforeRead() {
-	const result = await maybeAutoUpdateBackup();
+	let result: Awaited<ReturnType<typeof maybeAutoUpdateBackup>>;
+	try {
+		result = await maybeAutoUpdateBackup();
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(`birdclaw backup auto-sync failed: ${message}`);
+		return;
+	}
 	if (!result.ok) {
 		console.error(`birdclaw backup auto-sync failed: ${result.error}`);
 	}
 }
 
 async function autoSyncAfterWrite() {
-	const result = await maybeAutoSyncBackup();
+	let result: Awaited<ReturnType<typeof maybeAutoSyncBackup>>;
+	try {
+		result = await maybeAutoSyncBackup();
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(`birdclaw backup sync failed: ${message}`);
+		return;
+	}
 	if (!result.ok) {
 		console.error(`birdclaw backup sync failed: ${result.error}`);
 	}
@@ -298,14 +760,27 @@ program
 		);
 	});
 
-program
-	.command("auth status")
+const authCommand = program
+	.command("auth")
+	.description("Manage live transport");
+
+authCommand
+	.command("status")
 	.description("Show transport status")
 	.action(async () => {
 		const meta = await getQueryEnvelope();
 		print(meta.transport, program.opts().json ?? false);
 	});
 
+authCommand
+	.command("use <transport>")
+	.description("Set preferred moderation action transport")
+	.action((transport: string) => {
+		const parsed = parseActionsTransport(transport);
+		if (!parsed) return;
+		print(setActionsTransport(parsed), program.opts().json ?? false);
+	});
+
 program
 	.command("archive find")
 	.description("Find likely Twitter archives on disk")
@@ -342,9 +817,13 @@ importCommand
 			);
 		}
 
-		const result = await importArchive(resolvedArchivePath, { select });
+		const asJson = Boolean(program.opts().json);
+		const result = await importArchive(resolvedArchivePath, {
+			select,
+			onProgress: asJson ? undefined : logImportProgress,
+		});
 		await autoSyncAfterWrite();
-		print(result, program.opts().json ?? false);
+		print(result, asJson);
 	});
 
 importCommand
@@ -416,12 +895,13 @@ searchCommand
 
 searchCommand
 	.command("dms <query>")
+	.option("--inbox <kind>", "all, accepted, or requests", "all")
 	.option("--participant <value>")
 	.option("--min-followers <n>", "Minimum sender follower count")
 	.option("--max-followers <n>", "Maximum sender follower count")
 	.option("--min-influence-score <n>", "Minimum derived influence score")
 	.option("--max-influence-score <n>", "Maximum derived influence score")
-	.option("--sort <mode>", "recent or influence", "recent")
+	.option("--sort <mode>", "recent or followers", "recent")
 	.option(
 		"--context <n>",
 		"Include N messages before and after each match",
@@ -447,6 +927,10 @@ searchCommand
 		if (context === undefined) {
 			return;
 		}
+		const inbox = parseDmInboxOption(options.inbox);
+		if (inbox === undefined) {
+			return;
+		}
 		const replyFilter = options.replied
 			? "replied"
 			: options.unreplied
@@ -454,6 +938,7 @@ searchCommand
 				: "all";
 		const dmQuery = {
 			search: query,
+			...(inbox !== "all" ? { inbox } : {}),
 			participant: options.participant,
 			minFollowers: options.minFollowers
 				? Number(options.minFollowers)
@@ -467,7 +952,10 @@ searchCommand
 			maxInfluenceScore: options.maxInfluenceScore
 				? Number(options.maxInfluenceScore)
 				: undefined,
-			sort: options.sort === "influence" ? "influence" : "recent",
+			sort:
+				options.sort === "followers" || options.sort === "influence"
+					? "followers"
+					: "recent",
 			replyFilter,
 			context,
 			limit: Number(options.limit),
@@ -720,6 +1208,106 @@ program
 		);
 	});
 
+program
+	.command("discuss <query>")
+	.description("Search live/local tweets and summarize the results with AI")
+	.option("--account <accountId>", "Account id")
+	.option(
+		"--source <source>",
+		"all, search, home, mentions, authored, likes, or bookmarks",
+		"search",
+	)
+	.option("--mode <mode>", "auto, bird, xurl, or local", "xurl")
+	.option("--include-dms", "Include private DM search matches")
+	.option("--since <isoDate>", "Include matches created at or after this date")
+	.option("--until <isoDate>", "Include matches created before this date")
+	.option("--question <prompt>", "Discussion question or angle")
+	.option("--originals-only", "Exclude authored replies that start with @")
+	.option("--hide-low-quality", "Hide RTs, tiny replies, and link-only noise")
+	.option("--model <model>", "OpenAI model id")
+	.option("--refresh", "Bypass the local discussion cache")
+	.option("--limit <n>", "Maximum tweet context", "20000")
+	.option("--max-pages <n>", "Maximum live search pages", "200")
+	.action(async (query, options) => {
+		await autoUpdateBeforeRead();
+		const discussionOptions = buildSearchDiscussionOptions(query, options);
+		if (!discussionOptions) return;
+		await runSearchDiscussionCli(discussionOptions);
+	});
+
+program
+	.command("profile-analyze <handle>")
+	.alias("profile-analyse")
+	.description("Backfill a profile with xurl and summarize it with AI")
+	.option("--account <accountId>", "Account id")
+	.option("--model <model>", "OpenAI model id")
+	.option("--refresh", "Bypass profile fetch and analysis caches")
+	.option("--max-tweets <n>", "Maximum profile tweets", "10000")
+	.option("--max-pages <n>", "Maximum profile timeline pages", "100")
+	.option("--max-conversations <n>", "Maximum conversations to backfill", "80")
+	.option("--max-conversation-pages <n>", "Maximum pages per conversation", "3")
+	.option(
+		"--conversation-delay-ms <n>",
+		"Delay between conversation search calls",
+	)
+	.option(
+		"--rate-limit-retry-ms <n>",
+		"Delay before retrying conversation 429s",
+	)
+	.option("--rate-limit-retries <n>", "Conversation 429 retry count")
+	.action(async (handle, options) => {
+		await autoUpdateBeforeRead();
+		const analysisOptions = buildProfileAnalysisOptions(handle, options);
+		if (!analysisOptions) return;
+		await runProfileAnalysisCli(analysisOptions);
+	});
+
+program
+	.command("today")
+	.description("Stream an AI digest of what happened today")
+	.option("--account <accountId>", "Account id")
+	.option("--include-dms", "Include private DM context")
+	.option("--model <model>", "OpenAI model id")
+	.option("--refresh", "Bypass the local digest cache")
+	.option("--max-tweets <n>", "Maximum tweet context", "5000")
+	.option("--max-links <n>", "Maximum linked articles", "12")
+	.option("--no-live-sync", "Use only the local database")
+	.option(
+		"--live-mode <mode>",
+		"Live timeline mode: xurl, bird, or auto",
+		"xurl",
+	)
+	.action(async (options) => {
+		await autoUpdateBeforeRead();
+		const digestOptions = buildDigestOptions("today", options);
+		if (!digestOptions) return;
+		await runDigestCli(digestOptions);
+	});
+
+program
+	.command("digest [period]")
+	.description("Stream an AI digest for today, 24h, yesterday, or week")
+	.option("--account <accountId>", "Account id")
+	.option("--include-dms", "Include private DM context")
+	.option("--since <isoDate>", "Start of explicit window")
+	.option("--until <isoDate>", "End of explicit window")
+	.option("--model <model>", "OpenAI model id")
+	.option("--refresh", "Bypass the local digest cache")
+	.option("--max-tweets <n>", "Maximum tweet context", "5000")
+	.option("--max-links <n>", "Maximum linked articles", "12")
+	.option("--no-live-sync", "Use only the local database")
+	.option(
+		"--live-mode <mode>",
+		"Live timeline mode: xurl, bird, or auto",
+		"xurl",
+	)
+	.action(async (period, options) => {
+		await autoUpdateBeforeRead();
+		const digestOptions = buildDigestOptions(period, options);
+		if (!digestOptions) return;
+		await runDigestCli(digestOptions);
+	});
+
 const mentionsCommand = program
 	.command("mentions")
 	.description("Export local mention tweets for scripts and agents");
@@ -728,7 +1316,7 @@ mentionsCommand
 	.command("export [query]")
 	.description("Return mention tweets with plain-text and markdown renderings")
 	.option("--account <accountId>", "Account id")
-	.option("--mode <mode>", "birdclaw, xurl, or bird")
+	.option("--mode <mode>", "birdclaw, auto, xurl, or bird")
 	.option("--replied", "Only replied items")
 	.option("--unreplied", "Only unreplied items")
 	.option("--refresh", "Refresh the live xurl cache before returning")
@@ -748,23 +1336,14 @@ mentionsCommand
 				: "all";
 		const limit = Number(options.limit);
 		const mode = resolveMentionsDataSource(options.mode);
-		if (mode === "xurl") {
-			const payload = await exportMentionsViaCachedXurl({
-				account: options.account,
-				search: query,
-				replyFilter,
-				limit,
-				all: Boolean(options.all) || options.maxPages !== undefined,
-				maxPages: options.maxPages ? Number(options.maxPages) : undefined,
-				refresh: Boolean(options.refresh),
-				cacheTtlMs: Number(options.cacheTtl) * 1000,
-			});
-			await autoSyncAfterWrite();
-			print(payload, true);
-			return;
-		}
-		if (mode === "bird") {
-			const payload = await exportMentionsViaCachedBird({
+		if (mode === "xurl" || mode === "bird" || mode === "auto") {
+			const exportFn =
+				mode === "xurl"
+					? exportMentionsViaCachedXurl
+					: mode === "bird"
+						? exportMentionsViaCachedBird
+						: exportMentionsViaCachedAuto;
+			const payload = await exportFn({
 				account: options.account,
 				search: query,
 				replyFilter,
@@ -811,16 +1390,20 @@ const syncCommand = program
 
 syncCommand
 	.command("timeline")
-	.description("Refresh live home timeline through bird")
+	.description("Refresh live home timeline through xurl or bird")
 	.option("--account <accountId>", "Account id")
+	.option("--mode <mode>", "auto, xurl, or bird", "auto")
 	.option("--limit <n>", "Result limit", "100")
+	.option("--max-pages <n>", "Stop after N xurl pages", "3")
 	.option("--for-you", 'Fetch "For You" instead of chronological Following')
 	.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
 	.option("--refresh", "Bypass live-cache freshness window")
 	.action(async (options) => {
 		const result = await syncHomeTimeline({
 			account: options.account,
+			mode: options.mode,
 			limit: Number(options.limit),
+			maxPages: Number(options.maxPages),
 			following: !options.forYou,
 			refresh: Boolean(options.refresh),
 			cacheTtlMs: Number(options.cacheTtl) * 1000,
@@ -833,7 +1416,7 @@ syncCommand
 	.command("mentions")
 	.description("Refresh live mentions through xurl or bird")
 	.option("--account <accountId>", "Account id")
-	.option("--mode <mode>", "bird or xurl", "xurl")
+	.option("--mode <mode>", "auto, bird, or xurl", "auto")
 	.option("--limit <n>", "Result limit per page", "20")
 	.option("--max-pages <n>", "Stop after N pages")
 	.option("--since-id <id>", "Fetch mentions newer than this tweet id")
@@ -1033,6 +1616,92 @@ const jobsCommand = program
 	.command("jobs")
 	.description("Run and install background Birdclaw jobs");
 
+jobsCommand
+	.command("sync-account")
+	.description("Refresh live account timelines and append a JSONL audit entry")
+	.option("--account <accountId>", "Account id")
+	.option(
+		"--steps <steps>",
+		"Comma list: timeline,mentions,mention-threads,likes,bookmarks,dms",
+	)
+	.option("--mode <mode>", "auto, xurl, or bird for likes/bookmarks", "auto")
+	.option("--limit <n>", "Per-page/result limit", "100")
+	.option("--max-pages <n>", "Stop after N pages", "3")
+	.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
+	.option("--refresh", "Bypass live-cache freshness window")
+	.option(
+		"--allow-bird-account",
+		"Assert bird cookies match --account for Bird-backed steps",
+	)
+	.option("--log <path>", "Audit JSONL path")
+	.action(async (options) => {
+		const result = await runAccountSyncJob({
+			account: options.account,
+			steps: parseAccountSyncSteps(options.steps),
+			mode: options.mode as TimelineCollectionMode,
+			limit: Number(options.limit),
+			maxPages: Number(options.maxPages),
+			refresh: Boolean(options.refresh),
+			cacheTtlMs: Number(options.cacheTtl) * 1000,
+			allowBirdAccount: Boolean(options.allowBirdAccount),
+			logPath: options.log,
+		});
+		print(result, true);
+		if (!result.ok) {
+			process.exitCode = 1;
+		}
+	});
+
+jobsCommand
+	.command("install-account-launchd")
+	.description("Install a LaunchAgent that runs account sync")
+	.option("--label <label>", "LaunchAgent label")
+	.option("--interval-seconds <seconds>", "Launch interval", "1800")
+	.option("--program <path>", "birdclaw executable or command", "birdclaw")
+	.option("--account <accountId>", "Account id")
+	.option(
+		"--steps <steps>",
+		"Comma list: timeline,mentions,mention-threads,likes,bookmarks,dms",
+	)
+	.option("--mode <mode>", "auto, xurl, or bird for likes/bookmarks", "auto")
+	.option("--limit <n>", "Per-page/result limit", "100")
+	.option("--max-pages <n>", "Stop after N pages", "3")
+	.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
+	.option("--no-refresh", "Allow live-cache reuse")
+	.option(
+		"--allow-bird-account",
+		"Assert bird cookies match --account for Bird-backed steps",
+	)
+	.option("--log <path>", "Audit JSONL path")
+	.option("--env-path <path>", "Shell env file to source before running")
+	.option("--env-file <path>", "Deprecated alias for --env-path")
+	.option("--stdout <path>", "launchd stdout path")
+	.option("--stderr <path>", "launchd stderr path")
+	.option("--launch-agents-dir <path>", "LaunchAgents directory")
+	.option("--no-load", "Write plist without loading it")
+	.action(async (options) => {
+		const result = await installAccountSyncLaunchAgent({
+			label: options.label,
+			intervalSeconds: Number(options.intervalSeconds),
+			program: options.program,
+			account: options.account,
+			steps: parseAccountSyncSteps(options.steps),
+			mode: options.mode as TimelineCollectionMode,
+			limit: Number(options.limit),
+			maxPages: Number(options.maxPages),
+			refresh: options.refresh,
+			allowBirdAccount: Boolean(options.allowBirdAccount),
+			cacheTtlSeconds: Number(options.cacheTtl),
+			logPath: options.log,
+			envFile: options.envPath ?? options.envFile,
+			stdoutPath: options.stdout,
+			stderrPath: options.stderr,
+			launchAgentsDir: options.launchAgentsDir,
+			load: options.load,
+		});
+		print(result, true);
+	});
+
 jobsCommand
 	.command("sync-bookmarks")
 	.description("Refresh live bookmarks and append a JSONL audit entry")
@@ -1074,7 +1743,8 @@ jobsCommand
 	.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
 	.option("--no-refresh", "Allow live-cache reuse")
 	.option("--log <path>", "Audit JSONL path")
-	.option("--env-file <path>", "Shell env file to source before running")
+	.option("--env-path <path>", "Shell env file to source before running")
+	.option("--env-file <path>", "Deprecated alias for --env-path")
 	.option("--stdout <path>", "launchd stdout path")
 	.option("--stderr <path>", "launchd stderr path")
 	.option("--launch-agents-dir <path>", "LaunchAgents directory")
@@ -1091,7 +1761,7 @@ jobsCommand
 			refresh: options.refresh,
 			cacheTtlSeconds: Number(options.cacheTtl),
 			logPath: options.log,
-			envFile: options.envFile,
+			envFile: options.envPath ?? options.envFile,
 			stdoutPath: options.stdout,
 			stderrPath: options.stderr,
 			launchAgentsDir: options.launchAgentsDir,
@@ -1103,14 +1773,19 @@ jobsCommand
 dmsCommand
 	.command("list")
 	.option("--account <accountId>", "Account id")
-	.option("--refresh", "Refresh live DMs through bird before listing")
+	.option("--mode <mode>", "auto, bird, or xurl", "bird")
+	.option("--refresh", "Refresh live DMs before listing")
 	.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
+	.option("--inbox <kind>", "all, accepted, or requests", "all")
+	.option("--max-pages <n>", "Additional accepted/request pages to sync", "0")
+	.option("--all-pages", "Fetch all accepted/request pages while syncing")
+	.option("--page-delay-ms <n>", "Delay between live DM page requests", "0")
 	.option("--participant <value>")
 	.option("--min-followers <n>", "Minimum sender follower count")
 	.option("--max-followers <n>", "Maximum sender follower count")
 	.option("--min-influence-score <n>", "Minimum derived influence score")
 	.option("--max-influence-score <n>", "Maximum derived influence score")
-	.option("--sort <mode>", "recent or influence", "recent")
+	.option("--sort <mode>", "recent or followers", "recent")
 	.option(
 		"--resolve-profiles",
 		"Resolve placeholder DM profiles through cache/bird/xurl",
@@ -1131,10 +1806,33 @@ dmsCommand
 			: options.unreplied
 				? "unreplied"
 				: "all";
+		const inbox = parseDmInboxOption(options.inbox);
+		const mode = parseDmSyncModeOption(options.mode);
+		const maxPages = parseNonNegativeIntegerOption(
+			options.maxPages,
+			"--max-pages",
+		);
+		const pageDelayMs = parseNonNegativeIntegerOption(
+			options.pageDelayMs,
+			"--page-delay-ms",
+		);
+		if (
+			inbox === undefined ||
+			mode === undefined ||
+			maxPages === undefined ||
+			pageDelayMs === undefined
+		) {
+			return;
+		}
 		if (options.refresh) {
 			await syncDirectMessagesViaCachedBird({
 				account: options.account,
+				mode,
 				limit: Number(options.limit),
+				...(inbox !== "all" ? { inbox } : {}),
+				...(maxPages > 0 ? { maxPages } : {}),
+				...(options.allPages ? { allPages: true } : {}),
+				...(pageDelayMs > 0 ? { pageDelayMs } : {}),
 				refresh: true,
 				cacheTtlMs: Number(options.cacheTtl) * 1000,
 			});
@@ -1145,6 +1843,7 @@ dmsCommand
 		const items = await enrichDmItems(
 			{
 				account: options.account,
+				...(inbox !== "all" ? { inbox } : {}),
 				participant: options.participant,
 				minFollowers: options.minFollowers
 					? Number(options.minFollowers)
@@ -1158,7 +1857,10 @@ dmsCommand
 				maxInfluenceScore: options.maxInfluenceScore
 					? Number(options.maxInfluenceScore)
 					: undefined,
-				sort: options.sort === "influence" ? "influence" : "recent",
+				sort:
+					options.sort === "followers" || options.sort === "influence"
+						? "followers"
+						: "recent",
 				replyFilter,
 				limit: Number(options.limit),
 			},
@@ -1175,15 +1877,43 @@ dmsCommand
 
 dmsCommand
 	.command("sync")
-	.description("Refresh live direct messages through bird into the local store")
+	.description("Refresh live direct messages into the local store")
 	.option("--account <accountId>", "Account id")
+	.option("--mode <mode>", "auto, bird, or xurl", "bird")
 	.option("--limit <n>", "Limit messages", "20")
+	.option("--inbox <kind>", "all, accepted, or requests", "all")
+	.option("--max-pages <n>", "Additional accepted/request pages to sync", "0")
+	.option("--all-pages", "Fetch all accepted/request pages")
+	.option("--page-delay-ms <n>", "Delay between live DM page requests", "0")
 	.option("--cache-ttl <seconds>", "Live-cache freshness window", "120")
 	.option("--refresh", "Bypass live-cache freshness window")
 	.action(async (options) => {
+		const inbox = parseDmInboxOption(options.inbox);
+		const mode = parseDmSyncModeOption(options.mode);
+		const maxPages = parseNonNegativeIntegerOption(
+			options.maxPages,
+			"--max-pages",
+		);
+		const pageDelayMs = parseNonNegativeIntegerOption(
+			options.pageDelayMs,
+			"--page-delay-ms",
+		);
+		if (
+			inbox === undefined ||
+			mode === undefined ||
+			maxPages === undefined ||
+			pageDelayMs === undefined
+		) {
+			return;
+		}
 		const result = await syncDirectMessagesViaCachedBird({
 			account: options.account,
+			mode,
 			limit: Number(options.limit),
+			...(inbox !== "all" ? { inbox } : {}),
+			...(maxPages > 0 ? { maxPages } : {}),
+			...(options.allPages ? { allPages: true } : {}),
+			...(pageDelayMs > 0 ? { pageDelayMs } : {}),
 			refresh: Boolean(options.refresh),
 			cacheTtlMs: Number(options.cacheTtl) * 1000,
 		});
@@ -1191,6 +1921,39 @@ dmsCommand
 		print(result, true);
 	});
 
+for (const action of ["accept", "reject", "block"] as const) {
+	const command = dmsCommand
+		.command(`${action} <conversationId>`)
+		.description(`${action} a live DM message request through bird`);
+	if (action === "block") {
+		command
+			.option("--max-pages <n>", "Additional timeline pages to search", "3")
+			.option("--all-pages", "Search all accepted/request timeline pages");
+	}
+	command.action(async (conversationId, options) => {
+		const maxPages =
+			action === "block"
+				? parseNonNegativeIntegerOption(options.maxPages, "--max-pages")
+				: undefined;
+		if (action === "block" && maxPages === undefined) {
+			return;
+		}
+		const result = await runDirectMessageRequestMutationViaBird({
+			action,
+			conversationId,
+			...(action === "block" && maxPages !== undefined ? { maxPages } : {}),
+			...(action === "block" && options.allPages ? { allPages: true } : {}),
+		});
+		if (result.success) {
+			applyDmRequestMutationToLocalStore(conversationId, action);
+		} else {
+			process.exitCode = 1;
+		}
+		await autoSyncAfterWrite();
+		print(result, true);
+	});
+}
+
 registerModerationCommands({
 	program,
 	print,
@@ -1470,9 +2233,17 @@ program
 		await autoUpdateBeforeRead();
 		const child = spawn(
 			process.execPath,
-			["node_modules/vite/bin/vite.js", "dev", "--port", "3000"],
+			[
+				"node_modules/vite/bin/vite.js",
+				"dev",
+				"--host",
+				"127.0.0.1",
+				"--port",
+				"3000",
+			],
 			{
 				cwd: packageRoot,
+				env: { ...process.env, BIRDCLAW_LOCAL_WEB: "1" },
 				stdio: "inherit",
 				detached: process.platform !== "win32",
 			},
@@ -1527,7 +2298,11 @@ program
 	});
 
 export async function runCli(argv = process.argv) {
-	await program.parseAsync(argv);
+	try {
+		await program.parseAsync(argv);
+	} finally {
+		await closeDatabase();
+	}
 }
 
 /* v8 ignore next 5 */