@gperezmz/bb-plugin-thread-glance 0.1.2

package/features/thread-list/testing/fixtures.ts

@@ -0,0 +1,162 @@
+// Test fixtures: sidebar threads, projects and a ready-made view builder.
+import type {
+  PluginSidebarProject,
+  PluginSidebarSection,
+  PluginSidebarThread,
+} from "@get-bb/plugin-sdk/app";
+import { defaultPreferences, type Preferences } from "@/shared/preferences";
+import { buildForest, type Forest } from "../model/families";
+import { buildListView, type ListFilter, type ListView } from "../model/view";
+import type { Targets } from "../model/expansion";
+
+export const T0 = 1_780_000_000_000;
+
+type ThreadOverrides = Omit<Partial<PluginSidebarThread>, "activity" | "environment"> & {
+  id: string;
+  activity?: Partial<PluginSidebarThread["activity"]>;
+  environment?: Partial<NonNullable<PluginSidebarThread["environment"]>> | null;
+};
+
+/** A read, idle root thread in `proj_a`, created at T0. */
+export function makeThread(overrides: ThreadOverrides): PluginSidebarThread {
+  const { activity, environment, ...rest } = overrides;
+  const title = rest.title ?? `Thread ${overrides.id}`;
+  return {
+    projectId: "proj_a",
+    title,
+    titleFallback: null,
+    displayTitle: rest.displayTitle ?? title,
+    parentThreadId: null,
+    lifecycleOwnerThreadId: null,
+    sourceThreadId: null,
+    sectionId: null,
+    originKind: null,
+    originPluginId: null,
+    providerId: "claude-code",
+    status: "idle",
+    runtimeStatus: "idle",
+    queuedWork: "none",
+    hasPendingInteraction: false,
+    indicator: "none",
+    indicatorLabel: null,
+    isUnread: false,
+    isPinned: false,
+    pinnedAt: null,
+    pinSortKey: null,
+    isArchived: false,
+    archivedAt: null,
+    href: `/projects/${rest.projectId ?? "proj_a"}/threads/${overrides.id}`,
+    isHidden: false,
+    host: { id: "host_1", name: "Laptop" },
+    createdAt: T0,
+    updatedAt: T0,
+    lastReadAt: T0,
+    latestAttentionAt: T0,
+    ...rest,
+    activity: {
+      workflows: 0,
+      backgroundAgents: 0,
+      backgroundCommands: 0,
+      planMode: 0,
+      goals: 0,
+      ...activity,
+    },
+    environment:
+      environment === null
+        ? null
+        : {
+            id: "env_main",
+            name: null,
+            branchName: "main",
+            path: "/work/repo",
+            isWorktree: false,
+            providerId: null,
+            workspaceDisplayKind: null,
+            ...environment,
+          },
+  } as PluginSidebarThread;
+}
+
+export const working = { status: "active", runtimeStatus: "active" } as const;
+export const failedUnread = { status: "error", latestAttentionAt: T0 + 10, lastReadAt: T0 } as const;
+export const finishedUnread = { status: "idle", latestAttentionAt: T0 + 10, lastReadAt: T0 } as const;
+
+export function makeProject(
+  id: string,
+  name = id,
+  overrides: Partial<PluginSidebarProject> = {},
+): PluginSidebarProject {
+  return {
+    id,
+    name,
+    isPersonal: false,
+    href: `/projects/${id}`,
+    settingsHref: `/projects/${id}/settings`,
+    ...overrides,
+  };
+}
+
+export const PROJECTS: PluginSidebarProject[] = [
+  makeProject("proj_personal", "Personal", { isPersonal: true }),
+  makeProject("proj_a", "Alpha"),
+  makeProject("proj_b", "Beta"),
+];
+
+export interface Scenario {
+  threads: PluginSidebarThread[];
+  projects?: PluginSidebarProject[];
+  sections?: PluginSidebarSection[];
+  prefs?: Partial<Preferences>;
+  filter?: ListFilter;
+  activeThreadId?: string | null;
+  targets?: Targets;
+  finishedAt?: Record<string, number>;
+  seenAt?: Record<string, number>;
+  scheduled?: Record<string, number>;
+  draftIds?: string[];
+  notes?: Record<string, import("@/shared/contract").ThreadNotes>;
+  now?: number;
+}
+
+export function forestOf(scenario: Scenario): Forest {
+  return buildForest({
+    threads: scenario.threads,
+    activeThreadId: scenario.activeThreadId ?? null,
+    finishedAt: scenario.finishedAt ?? {},
+    seenAt: scenario.seenAt ?? {},
+    scheduled: scenario.scheduled ?? {},
+    draftIds: new Set(scenario.draftIds ?? []),
+    notes: scenario.notes ?? {},
+    childAttention: scenario.prefs?.childAttention,
+    now: scenario.now ?? T0 + 60_000,
+  });
+}
+
+export function viewOf(scenario: Scenario): ListView {
+  const forest = forestOf(scenario);
+  return buildListView({
+    forest,
+    threads: scenario.threads,
+    projects: scenario.projects ?? PROJECTS,
+    sections: scenario.sections ?? [],
+    prefs: { ...defaultPreferences(), ...scenario.prefs },
+    filter: scenario.filter ?? "all",
+    activeThreadId: scenario.activeThreadId ?? null,
+    targets: scenario.targets ?? new Map(),
+  });
+}
+
+/** Thread ids in the group's rows, in order; older rows as `older:N`. */
+export function rowIds(view: ListView, groupId: string): string[] {
+  const group = [...view.groups, ...view.more].find((candidate) => candidate.descriptor.id === groupId);
+  if (group === undefined) throw new Error(`no group ${groupId}`);
+  return group.rows.map((row) =>
+    row.type === "thread"
+      ? row.info.thread.id
+      : row.type === "older"
+        ? `older:${row.count}`
+        : row.type === "empty"
+          ? `empty:${row.scopeId}`
+          : `env:${row.environmentId}`,
+  );
+}

package/hooks/useBrowserDimmingModal.ts

@@ -0,0 +1,5 @@
+export function useBrowserDimmingModal(_active: boolean): void {}
+
+export function useIsBrowserDimmingModalOpen(): boolean {
+  return false;
+}

package/lib/portal-scope.ts

@@ -0,0 +1,15 @@
+declare const __BB_PLUGIN_ID__: string | undefined;
+
+export function usePortalScopeProps(): {
+  "data-bb-portaled-overlay": "";
+  "data-bb-plugin-root"?: "";
+  "data-bb-plugin"?: string;
+} {
+  const pluginId =
+    typeof __BB_PLUGIN_ID__ === "string" ? __BB_PLUGIN_ID__ : undefined;
+  return {
+    "data-bb-portaled-overlay": "",
+    "data-bb-plugin-root": "",
+    ...(pluginId !== undefined ? { "data-bb-plugin": pluginId } : {}),
+  };
+}

package/lib/utils.ts

@@ -0,0 +1,17 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+export function formatHomePathForDisplay(pathValue: string): string {
+  const homePrefix =
+    pathValue.match(/^\/Users\/[^/]+(?=\/|$)/)?.[0] ??
+    pathValue.match(/^\/home\/[^/]+(?=\/|$)/)?.[0] ??
+    pathValue.match(/^\/root(?=\/|$)/)?.[0] ??
+    pathValue.match(/^[A-Za-z]:[\\/]Users[\\/][^\\/]+(?=[\\/]|$)/i)?.[0];
+  return homePrefix === undefined
+    ? pathValue
+    : `~${pathValue.slice(homePrefix.length)}`;
+}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@gperezmz/bb-plugin-thread-glance",
+  "version": "0.1.2",
+  "type": "module",
+  "engines": {
+    "bb": ">=0.43",
+    "bbPluginSdk": ">=0.5.9"
+  },
+  "bb": {
+    "name": "Thread Glance",
+    "description": "Sidebar thread list that shows each thread's state, harness and child threads at a glance.",
+    "branding": {
+      "icon": "ListView"
+    },
+    "server": "./server.ts",
+    "app": "./app.tsx",
+    "skills": [
+      "skills"
+    ]
+  },
+  "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@hugeicons/core-free-icons": "^4.3.4",
+    "@hugeicons/react": "^1.1.6",
+    "@radix-ui/react-slot": "^1.3.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@get-bb/plugin-sdk": "0.5.9",
+    "@pierre/diffs": "^1.2.9",
+    "@radix-ui/react-alert-dialog": "^1.1.19",
+    "@radix-ui/react-context-menu": "^2.3.3",
+    "@radix-ui/react-dialog": "^1.1.19",
+    "@radix-ui/react-dropdown-menu": "^2.1.20",
+    "@radix-ui/react-hover-card": "^1.1.19",
+    "@radix-ui/react-menubar": "^1.1.20",
+    "@radix-ui/react-navigation-menu": "^1.2.18",
+    "@radix-ui/react-popover": "^1.1.19",
+    "@radix-ui/react-select": "^2.3.3",
+    "@radix-ui/react-tooltip": "^1.2.12",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "better-sqlite3": "^12.0.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cron-parser": "^5.5.0",
+    "esbuild": "^0.28.2",
+    "hono": "^4.11.9",
+    "jsdom": "^30.1.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "sonner": "^1.7.4",
+    "tailwind-merge": "^3.4.0",
+    "typescript": "^7.0.2",
+    "vaul": "^1.1.2",
+    "vitest": "^5.0.1"
+  },
+  "description": "Sidebar thread list that shows each thread's state, harness and child threads at a glance.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gperezmz/bb-plugins.git",
+    "directory": "plugins/thread-glance"
+  },
+  "keywords": [
+    "bb-plugin"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "build": "bb plugin build",
+    "notices": "node scripts/third-party-notices.mjs",
+    "perf": "vitest run --config perf/vitest.config.ts"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "server.ts",
+    "tsconfig.json",
+    "THIRD_PARTY_NOTICES.md",
+    "app.tsx",
+    "server",
+    "shared",
+    "features",
+    "components",
+    "lib",
+    "hooks",
+    "types",
+    "!**/*.test.*"
+  ]
+}

package/server/cli.ts

@@ -0,0 +1,107 @@
+// `bb thread-glance prefs …`, the same commands and errors as bb's
+// `bb thread-list prefs …`. Writes go through the store, so they publish.
+import { PluginCliError, cliCommand, defineCli, type PluginCliRegistration } from "@get-bb/plugin-sdk";
+import {
+  PREFERENCE_KEYS,
+  describePreference,
+  isPreferenceKey,
+  type PreferenceKey,
+} from "../shared/preferences";
+import { PreferenceValidationError, type PreferenceStore } from "./preference-store";
+
+/** Parses a CLI value as JSON; a bare word such as `tree` is read as a string. */
+export function parseCliValue(raw: string): unknown {
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return raw;
+  }
+}
+
+function requirePreferenceKey(key: string): PreferenceKey {
+  if (isPreferenceKey(key)) return key;
+  throw new PluginCliError(`Unknown preference: ${key}`, {
+    code: "unknown_preference",
+    hint: `Known preferences: ${PREFERENCE_KEYS.join(", ")}.`,
+  });
+}
+
+const jsonOption = { type: "boolean", description: "Emit machine-readable JSON" } as const;
+const keyPositional = { name: "key", description: "Preference name", required: true } as const;
+
+export function createCli(store: PreferenceStore): PluginCliRegistration {
+  function keyValueOutput(key: PreferenceKey, value: unknown, json: boolean): string {
+    return json ? JSON.stringify({ key, value }) : `${key} = ${JSON.stringify(value)}`;
+  }
+
+  return defineCli({
+    name: "thread-glance",
+    summary: "Inspect and change the Thread Glance sidebar's layout preferences",
+    description:
+      "Organization, sort, group order, hidden and collapsed groups, child nesting and folding for the Thread Glance sidebar. Values are JSON; a bare word is read as a string.",
+    commands: {
+      "prefs list": cliCommand({
+        summary: "List every preference and its current value",
+        options: { json: jsonOption },
+        async run(input) {
+          const preferences = await store.readAll();
+          if (input.options.json) return { exitCode: 0, stdout: JSON.stringify(preferences) };
+          const lines = PREFERENCE_KEYS.map(
+            (key) => `${key}\t${JSON.stringify(preferences[key])}\t${describePreference(key)}`,
+          );
+          return { exitCode: 0, stdout: lines.join("\n") };
+        },
+      }),
+      "prefs get": cliCommand({
+        summary: "Print one preference",
+        positionals: [keyPositional],
+        options: { json: jsonOption },
+        async run(input) {
+          const key = requirePreferenceKey(input.positionals.key);
+          const value = await store.read(key);
+          return {
+            exitCode: 0,
+            stdout: input.options.json ? JSON.stringify({ key, value }) : JSON.stringify(value),
+          };
+        },
+      }),
+      "prefs set": cliCommand({
+        summary: "Set one preference",
+        positionals: [
+          keyPositional,
+          {
+            name: "value",
+            description: `JSON value, e.g. '"machine"' or '["pinned","threads"]'`,
+            required: true,
+          },
+        ] as const,
+        options: { json: jsonOption },
+        async run(input) {
+          const key = requirePreferenceKey(input.positionals.key);
+          try {
+            const value = await store.write(key, parseCliValue(input.positionals.value));
+            return { exitCode: 0, stdout: keyValueOutput(key, value, input.options.json === true) };
+          } catch (error) {
+            if (error instanceof PreferenceValidationError) {
+              throw new PluginCliError(error.message, {
+                code: "invalid_preference_value",
+                hint: describePreference(key),
+              });
+            }
+            throw error;
+          }
+        },
+      }),
+      "prefs reset": cliCommand({
+        summary: "Restore one preference to its default",
+        positionals: [keyPositional],
+        options: { json: jsonOption },
+        async run(input) {
+          const key = requirePreferenceKey(input.positionals.key);
+          const value = await store.reset(key);
+          return { exitCode: 0, stdout: keyValueOutput(key, value, input.options.json === true) };
+        },
+      }),
+    },
+  });
+}

package/server/failures.ts

@@ -0,0 +1,136 @@
+// The text of a thread's failed note. `thread.failed` often carries
+// `error: null`; the provider's message is in the thread's `provider/error`
+// event, and `turn.failed` carries a structured `errorInfo`.
+import type { BbPluginApi, PluginTurnFailedEvent } from "@get-bb/plugin-sdk";
+import { noteText } from "./notes";
+
+type ErrorInfo = NonNullable<PluginTurnFailedEvent["errorInfo"]>;
+
+/** Rows read from the end of the event log; the failing turn's error is near it. */
+const EVENT_TAIL_LIMIT = 20;
+const GENERIC_ERRORS = new Set(["error", "failed", "provider error", "turn failed", "unknown error"]);
+
+/** Whether an error string says nothing beyond "it failed". */
+export function isGenericError(text: string | null | undefined): boolean {
+  if (text === null || text === undefined) return true;
+  const normalized = text.trim().toLowerCase().replace(/[.!]+$/, "");
+  // bb's own "Command thread.start failed" names the step, not the cause.
+  return normalized === "" || GENERIC_ERRORS.has(normalized) || /^command [\w./:-]+ failed$/.test(normalized);
+}
+
+/** A short label for an error category, or null when it says nothing. */
+export function errorInfoLabel(info: ErrorInfo | null | undefined): string | null {
+  if (!info) return null;
+  const status = info.httpStatusCode === null ? "" : ` (${info.httpStatusCode})`;
+  switch (info.category) {
+    case "rate-limit":
+      return `Rate limited${status}`;
+    case "unauthorized":
+      return "Not signed in";
+    case "billing":
+    case "budget-exceeded":
+      return "Out of credits";
+    case "context-window-exceeded":
+      return "Context window full";
+    case "unknown":
+      return status === "" ? null : `Error${status}`;
+    default: {
+      const words = info.category.replace(/-/g, " ");
+      return `${words.charAt(0).toUpperCase()}${words.slice(1)}${status}`;
+    }
+  }
+}
+
+/** The fields of a `provider/error` event the note reads. */
+export interface ProviderErrorData {
+  message?: string;
+  detail?: string;
+  errorInfo?: ErrorInfo;
+}
+
+/** An event row as read here: newest first, `provider/error` and `turn/started` only. */
+export interface TailRow {
+  type: string;
+  scope?: { kind: string; turnId?: string };
+  data?: unknown;
+}
+
+/**
+ * The newest `provider/error` of the failing turn, from rows newest first.
+ *
+ * With a `turnId`, only an error scoped to that turn counts. Without one,
+ * the search stops at the newest `turn/started`, so an error from an earlier
+ * turn is not reported for this failure.
+ */
+export function latestProviderError(
+  rows: readonly TailRow[],
+  turnId: string | null,
+): ProviderErrorData | null {
+  for (const row of rows) {
+    if (row.type === "turn/started" && turnId === null) return null;
+    if (row.type !== "provider/error" && row.type !== "system/error") continue;
+    // A system error (a provider that never started) belongs to no turn.
+    if (turnId !== null && row.scope?.turnId !== undefined && row.scope.turnId !== turnId) continue;
+    return (row.data ?? {}) as ProviderErrorData;
+  }
+  return null;
+}
+
+/**
+ * The failure text from what is known, most specific first: a non-generic
+ * `error`, the provider error's `detail`, then its `message`, then a label
+ * from `errorInfo`. Null when none says more than "it failed".
+ */
+export function failureText(input: {
+  error: string | null;
+  providerError: ProviderErrorData | null;
+  errorInfo: ErrorInfo | null;
+}): string | null {
+  const candidates = [
+    input.error,
+    input.providerError?.detail,
+    input.providerError?.message,
+    errorInfoLabel(input.errorInfo ?? input.providerError?.errorInfo),
+  ];
+  for (const candidate of candidates) {
+    if (!isGenericError(candidate)) {
+      const text = noteText(candidate as string);
+      if (text !== "") return text;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolves a failure's text, reading the tail of the thread's event log when
+ * `error` is generic. A failed read is logged and treated as no event.
+ */
+export async function resolveFailureText(
+  bb: Pick<BbPluginApi, "sdk" | "log">,
+  failure: {
+    threadId: string;
+    error: string | null;
+    errorInfo: ErrorInfo | null;
+    turnId: string | null;
+  },
+): Promise<string | null> {
+  let providerError: ProviderErrorData | null = null;
+  if (isGenericError(failure.error)) {
+    try {
+      const rows = await bb.sdk.threads.events.list({
+        threadId: failure.threadId,
+        types: ["provider/error", "system/error", "turn/started"],
+        order: "desc",
+        limit: String(EVENT_TAIL_LIMIT),
+      });
+      providerError = latestProviderError(rows as readonly TailRow[], failure.turnId);
+    } catch (error) {
+      bb.log.warn(
+        `could not read events of ${failure.threadId} for its failure: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+  return failureText({ error: failure.error, providerError, errorInfo: failure.errorInfo });
+}

package/server/import.ts

@@ -0,0 +1,144 @@
+// First-run import of bb's own thread-list preferences.
+import { execFile } from "node:child_process";
+import type { BbPluginApi } from "@get-bb/plugin-sdk";
+import {
+  mapBbPreferences,
+  preferenceDefault,
+  type PreferenceKey,
+} from "../shared/preferences";
+import type { PreferenceStore } from "./preference-store";
+
+export const IMPORT_MARKER_KEY = "migration:import:v1";
+const CLI_TIMEOUT_MS = 5_000;
+const CLI_MAX_BUFFER_BYTES = 4 * 1024 * 1024;
+
+export type ImportSource = "local-storage" | "cli" | "none";
+
+export interface ImportResult {
+  status: "already-imported" | "imported" | "defaults";
+  source: ImportSource | null;
+  keys: PreferenceKey[];
+}
+
+/**
+ * Reads bb's preferences from its CLI and returns the parsed JSON, or null
+ * when the command fails or prints something that is not JSON.
+ */
+export type BbCliReader = () => Promise<unknown>;
+
+export interface ImportDeps {
+  kv: BbPluginApi["storage"]["kv"];
+  log: BbPluginApi["log"];
+  store: PreferenceStore;
+  readBbCli: BbCliReader;
+}
+
+/**
+ * Returns bb's preference object from a mirror or CLI value, or null when it
+ * holds no preferences.
+ *
+ * bb 0.43 writes both as a flat key-to-value object. A JSON string and a
+ * `{ preferences }` wrapper (the shape of bb's `listPreferences` RPC) are
+ * unwrapped too, so an app that sends the raw localStorage string or a newer
+ * bb that wraps the object still imports.
+ */
+export function unwrapBbPreferences(raw: unknown): Record<string, unknown> | null {
+  let value = raw;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value) as unknown;
+    } catch {
+      return null;
+    }
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const inner = record.preferences;
+  if (inner !== null && typeof inner === "object" && !Array.isArray(inner)) {
+    return inner as Record<string, unknown>;
+  }
+  return record;
+}
+
+/** The bb binary: `BB_CLI` when the server has it, else `bb` on PATH. */
+export function bbCliPath(env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env.BB_CLI?.trim();
+  return configured ? configured : "bb";
+}
+
+/** Runs `bb thread-list prefs list --json` with a 5 s timeout. */
+export function createBbCliReader(
+  log: BbPluginApi["log"],
+  env: NodeJS.ProcessEnv = process.env,
+): BbCliReader {
+  return () =>
+    new Promise((resolve) => {
+      const file = bbCliPath(env);
+      execFile(
+        file,
+        ["thread-list", "prefs", "list", "--json"],
+        { timeout: CLI_TIMEOUT_MS, maxBuffer: CLI_MAX_BUFFER_BYTES, encoding: "utf8" },
+        (error, stdout) => {
+          if (error) {
+            log.warn(`could not run ${file} thread-list prefs list: ${error.message}`);
+            resolve(null);
+            return;
+          }
+          try {
+            resolve(JSON.parse(stdout) as unknown);
+          } catch {
+            log.warn(`${file} thread-list prefs list printed output that is not JSON`);
+            resolve(null);
+          }
+        },
+      );
+    });
+}
+
+/**
+ * Imports bb's preferences once, from the first source that holds any:
+ * `bbMirror` (bb's localStorage mirror, sent by the app), then bb's CLI, then
+ * nothing. A key that already has a kv row keeps it, and a value equal to our
+ * default is not written. The marker is set whichever source won, so a later
+ * call returns `already-imported`.
+ */
+export async function importPreferences(
+  deps: ImportDeps,
+  bbMirror: unknown,
+): Promise<ImportResult> {
+  if ((await deps.kv.get<unknown>(IMPORT_MARKER_KEY)) !== undefined) {
+    return { status: "already-imported", source: null, keys: [] };
+  }
+
+  let source: ImportSource = "none";
+  let mapped: Record<string, unknown> = {};
+  const fromMirror = bbMirror === null ? null : unwrapBbPreferences(bbMirror);
+  const mirrorMapped = fromMirror === null ? {} : mapBbPreferences(fromMirror);
+  if (Object.keys(mirrorMapped).length > 0) {
+    source = "local-storage";
+    mapped = mirrorMapped;
+  } else {
+    const cli = unwrapBbPreferences(await deps.readBbCli());
+    const cliMapped = cli === null ? {} : mapBbPreferences(cli);
+    if (Object.keys(cliMapped).length > 0) {
+      source = "cli";
+      mapped = cliMapped;
+    }
+  }
+
+  const keys: PreferenceKey[] = [];
+  for (const [key, value] of Object.entries(mapped) as [PreferenceKey, unknown][]) {
+    if (await deps.store.isStored(key)) continue;
+    if (JSON.stringify(value) === JSON.stringify(preferenceDefault(key))) continue;
+    await deps.store.write(key, value);
+    keys.push(key);
+  }
+  await deps.kv.set(IMPORT_MARKER_KEY, { source, keys, at: Date.now() });
+
+  deps.log.info(
+    source === "none"
+      ? "no bb thread-list preferences found; using the defaults"
+      : `imported bb thread-list preferences from ${source}: ${keys.join(", ") || "none differ from the defaults"}`,
+  );
+  return { status: source === "none" ? "defaults" : "imported", source, keys };
+}