cue-ai 0.9.0 → 0.9.2

package/src/lib/debug-log.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { debug, debugEnabled } from "./debug-log";
+
+const SAVED = process.env.CUE_DEBUG;
+
+// Capture stderr writes without spilling to the test runner's output.
+function captureStderr(fn: () => void): string {
+  const orig = process.stderr.write.bind(process.stderr);
+  let buf = "";
+  // @ts-expect-error — narrow override for the test
+  process.stderr.write = (chunk: string) => {
+    buf += chunk;
+    return true;
+  };
+  try {
+    fn();
+  } finally {
+    process.stderr.write = orig;
+  }
+  return buf;
+}
+
+describe("debug-log", () => {
+  beforeEach(() => {
+    delete process.env.CUE_DEBUG;
+  });
+  afterEach(() => {
+    if (SAVED === undefined) delete process.env.CUE_DEBUG;
+    else process.env.CUE_DEBUG = SAVED;
+  });
+
+  test("debugEnabled is false when CUE_DEBUG unset / falsy", () => {
+    expect(debugEnabled()).toBe(false);
+    process.env.CUE_DEBUG = "";
+    expect(debugEnabled()).toBe(false);
+    process.env.CUE_DEBUG = "0";
+    expect(debugEnabled()).toBe(false);
+    process.env.CUE_DEBUG = "false";
+    expect(debugEnabled()).toBe(false);
+  });
+
+  test("debugEnabled is true for a truthy value", () => {
+    process.env.CUE_DEBUG = "1";
+    expect(debugEnabled()).toBe(true);
+  });
+
+  test("debug() is a silent no-op when disabled", () => {
+    const out = captureStderr(() => debug("scope", new Error("boom")));
+    expect(out).toBe("");
+  });
+
+  test("debug() writes a namespaced line with the error message when enabled", () => {
+    process.env.CUE_DEBUG = "1";
+    const out = captureStderr(() => debug("launch:autodetect", new Error("boom")));
+    expect(out).toContain("[cue:debug]");
+    expect(out).toContain("launch:autodetect");
+    expect(out).toContain("boom");
+  });
+
+  test("debug() handles a missing detail and non-Error values", () => {
+    process.env.CUE_DEBUG = "1";
+    expect(captureStderr(() => debug("scope"))).toContain("scope");
+    expect(captureStderr(() => debug("scope", { a: 1 }))).toContain('{"a":1}');
+  });
+});

package/src/lib/debug-log.ts

@@ -0,0 +1,45 @@
+/**
+ * Opt-in debug logging for cue's many best-effort code paths.
+ *
+ * cue deliberately swallows a lot of non-fatal errors (missing files, malformed
+ * JSON, absent optional tools) so one bad input never blocks a launch. That's
+ * correct, but it makes failures invisible when something genuinely IS wrong —
+ * the user sees a silent degradation with no signal. `debug()` surfaces those
+ * swallowed errors on stderr ONLY when `CUE_DEBUG` is set, so normal runs stay
+ * quiet and `CUE_DEBUG=1 cue …` turns into a diagnosis tool.
+ *
+ *   try { risky(); } catch (err) { debug("launch:autodetect", err); }
+ */
+
+/** True when CUE_DEBUG is set to a non-falsy value (`0`/`false`/empty = off). */
+export function debugEnabled(): boolean {
+  const v = process.env.CUE_DEBUG;
+  return v !== undefined && v !== "" && v !== "0" && v.toLowerCase() !== "false";
+}
+
+/** Render an arbitrary catch value to a single log string. */
+function format(detail: unknown): string {
+  if (detail === undefined) return "";
+  if (detail instanceof Error) return detail.stack ?? `${detail.name}: ${detail.message}`;
+  if (typeof detail === "string") return detail;
+  try {
+    return JSON.stringify(detail);
+  } catch {
+    return String(detail);
+  }
+}
+
+/**
+ * Emit a namespaced debug line to stderr when CUE_DEBUG is enabled; a no-op
+ * otherwise. `scope` is a short "area:step" tag (e.g. "launch:autodetect");
+ * `detail` is the swallowed error or a message. Never throws.
+ */
+export function debug(scope: string, detail?: unknown): void {
+  if (!debugEnabled()) return;
+  const rendered = format(detail);
+  try {
+    process.stderr.write(`[cue:debug] ${scope}${rendered ? ` — ${rendered}` : ""}\n`);
+  } catch {
+    /* stderr unavailable — debug logging must never itself break a run */
+  }
+}

package/src/lib/mcp-catalog.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Tests for the MCP catalog + profile-write helpers behind the studio's
+ * "Available in cue" section. Catalog reads run against the real on-disk
+ * sanitized configs; write tests redirect CUE_PROFILES_DIR to a temp tree so
+ * no real `profiles/*.yaml` is ever mutated.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { loadMcpCatalog, loadAllMcpIds, addMcpToProfile } from "./mcp-catalog";
+
+describe("loadMcpCatalog", () => {
+  test("returns the full catalog with inferred transport + install", () => {
+    const catalog = loadMcpCatalog();
+    expect(catalog.length).toBeGreaterThan(10);
+
+    // ids are unique + sorted
+    const ids = catalog.map((e) => e.id);
+    expect(new Set(ids).size).toBe(ids.length);
+    expect([...ids].sort((a, b) => a.localeCompare(b))).toEqual(ids);
+
+    // every entry has a concrete transport
+    for (const e of catalog) {
+      expect(["stdio", "sse", "http", "unknown"]).toContain(e.transport);
+    }
+
+    // a known stdio server resolves an install command
+    const coolify = catalog.find((e) => e.id === "coolify");
+    expect(coolify).toBeDefined();
+    expect(coolify!.transport).toBe("stdio");
+    expect(coolify!.install.length).toBeGreaterThan(0);
+  });
+
+  test("catalog ids match the add-validation registry exactly", () => {
+    // The UI must never offer an MCP the add path would reject.
+    expect(loadMcpCatalog().map((e) => e.id)).toEqual(loadAllMcpIds());
+  });
+});
+
+describe("addMcpToProfile", () => {
+  const created: string[] = [];
+  afterEach(async () => {
+    delete process.env.CUE_PROFILES_DIR;
+    for (const d of created.splice(0)) await rm(d, { recursive: true, force: true });
+  });
+
+  async function tempProfiles(yaml: string): Promise<string> {
+    const root = await mkdtemp(join(tmpdir(), "cue-mcp-test-"));
+    created.push(root);
+    await mkdir(join(root, "demo"), { recursive: true });
+    await writeFile(join(root, "demo", "profile.yaml"), yaml);
+    process.env.CUE_PROFILES_DIR = root;
+    return root;
+  }
+
+  test("rejects an id not in the catalog", async () => {
+    await tempProfiles("name: demo\nmcps:\n  - gbrain\n");
+    await expect(addMcpToProfile("totally-not-real", "demo")).rejects.toThrow(/unknown-mcp/);
+  });
+
+  test("rejects a path-traversal profile name", async () => {
+    await tempProfiles("name: demo\n");
+    await expect(addMcpToProfile("coolify", "../../etc")).rejects.toThrow(/invalid-profile/);
+  });
+
+  test("rejects a composite profile with no profile.yaml", async () => {
+    await tempProfiles("name: demo\n");
+    await expect(addMcpToProfile("coolify", "core+skill-writer")).rejects.toThrow(
+      /invalid-profile|not-a-physical-profile/,
+    );
+  });
+
+  test("appends a new id into an existing mcps: block", async () => {
+    const root = await tempProfiles("name: demo\nmcps:\n  - gbrain\nplugins:\n  - foo\n");
+    const res = await addMcpToProfile("coolify", "demo");
+    expect(res.alreadyPresent).toBe(false);
+    const written = await readFile(join(root, "demo", "profile.yaml"), "utf8");
+    expect(written).toContain("- gbrain");
+    expect(written).toContain("- coolify");
+    // inserted inside the mcps block, above plugins
+    expect(written.indexOf("- coolify")).toBeLessThan(written.indexOf("plugins:"));
+  });
+
+  test("creates an mcps: block when the profile has none", async () => {
+    const root = await tempProfiles("name: demo\nskills:\n  local: []\n");
+    await addMcpToProfile("coolify", "demo");
+    const written = await readFile(join(root, "demo", "profile.yaml"), "utf8");
+    expect(written).toMatch(/mcps:\n\s+- coolify/);
+  });
+
+  test("is idempotent when the id is already present", async () => {
+    const root = await tempProfiles("name: demo\nmcps:\n  - coolify\n");
+    const res = await addMcpToProfile("coolify", "demo");
+    expect(res.alreadyPresent).toBe(true);
+    const written = await readFile(join(root, "demo", "profile.yaml"), "utf8");
+    // not duplicated
+    expect(written.match(/- coolify/g)?.length).toBe(1);
+  });
+});

package/src/lib/mcp-catalog.ts

@@ -0,0 +1,193 @@
+/**
+ * MCP catalog + profile-write helpers, shared by the dashboard server's
+ * `/api/v1/mcps/catalog` and `/api/v1/mcps/add` endpoints.
+ *
+ * The "catalog" is the union of MCP server ids declared across cue's sanitized
+ * config snapshots (`resources/mcps/configs/*.sanitized.json`) — the same set
+ * `cue mcps add` validates against, so the studio never offers an MCP the CLI
+ * would then reject. Per-entry transport + install command are inferred from
+ * the server config; the description is the first prose line of the MCP's
+ * `README.md` when one exists (most catalog entries have none — that's fine,
+ * the card just shows the id).
+ *
+ * Paths are resolved per-call from env so tests can point CUE_PROFILES_DIR /
+ * CUE_REPO_ROOT at a fixture tree without a real write to `profiles/`.
+ */
+
+import { readFileSync } from "node:fs";
+import { readFile, writeFile, access } from "node:fs/promises";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function repoRoot(): string {
+  return (
+    process.env.CUE_REPO_ROOT ??
+    process.env.SOUL_REPO_ROOT ??
+    resolve(dirname(fileURLToPath(import.meta.url)), "..", "..")
+  );
+}
+function profilesDir(): string {
+  return process.env.CUE_PROFILES_DIR ?? join(repoRoot(), "profiles");
+}
+function configsDir(): string {
+  return join(repoRoot(), "resources", "mcps", "configs");
+}
+function docsDir(): string {
+  return join(repoRoot(), "resources", "mcps", "mcps");
+}
+
+const CONFIG_FILES = [
+  "claude.sanitized.json",
+  "claude_runtime.sanitized.json",
+  "codex.sanitized.json",
+] as const;
+
+export type McpTransport = "stdio" | "sse" | "http" | "unknown";
+
+export interface McpCatalogEntry {
+  id: string;
+  description: string;
+  transport: McpTransport;
+  install: string;
+}
+
+interface ServerConfig {
+  command?: string;
+  args?: string[];
+  url?: string;
+  type?: string;
+}
+
+/** Union of server ids across all sanitized config snapshots, sorted. */
+export function loadAllMcpIds(): string[] {
+  const ids = new Set<string>();
+  for (const file of CONFIG_FILES) {
+    try {
+      const raw = JSON.parse(readFileSync(join(configsDir(), file), "utf8"));
+      if (raw.servers) for (const id of Object.keys(raw.servers)) ids.add(id);
+    } catch {
+      /* file may not exist in every snapshot */
+    }
+  }
+  return [...ids].sort((a, b) => a.localeCompare(b));
+}
+
+/** First matching server config for `id` across the snapshots, or null. */
+function loadServerConfig(id: string): ServerConfig | null {
+  for (const file of CONFIG_FILES) {
+    try {
+      const raw = JSON.parse(readFileSync(join(configsDir(), file), "utf8"));
+      if (raw.servers?.[id]) return raw.servers[id] as ServerConfig;
+    } catch {
+      /* skip */
+    }
+  }
+  return null;
+}
+
+/** First prose line of the MCP's README.md (skipping headings), capped. */
+export function getMcpDescription(id: string): string {
+  try {
+    const readme = readFileSync(join(docsDir(), id, "README.md"), "utf8");
+    const firstLine = readme.split("\n").find((l) => l.trim() && !l.startsWith("#"));
+    return firstLine?.trim().slice(0, 140) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+function transportOf(cfg: ServerConfig | null): McpTransport {
+  if (!cfg) return "unknown";
+  if (cfg.type === "stdio" || cfg.type === "sse" || cfg.type === "http") return cfg.type;
+  if (cfg.url) return cfg.url.includes("/sse") ? "sse" : "http";
+  if (cfg.command) return "stdio";
+  return "unknown";
+}
+
+function installOf(cfg: ServerConfig | null): string {
+  if (!cfg) return "";
+  if (cfg.command) {
+    const args = cfg.args?.length ? " " + cfg.args.join(" ") : "";
+    return (cfg.command + args).trim();
+  }
+  if (cfg.url) return cfg.url;
+  return "";
+}
+
+/** Full catalog: every addable MCP with inferred transport + install hint. */
+export function loadMcpCatalog(): McpCatalogEntry[] {
+  return loadAllMcpIds().map((id) => {
+    const cfg = loadServerConfig(id);
+    return {
+      id,
+      description: getMcpDescription(id),
+      transport: transportOf(cfg),
+      install: installOf(cfg),
+    };
+  });
+}
+
+export interface AddMcpResult {
+  id: string;
+  profile: string;
+  alreadyPresent: boolean;
+}
+
+/**
+ * Append `id` to the `mcps:` list of `profileName`'s profile.yaml.
+ *
+ * `profileName` must be a single, physical profile (a `profiles/<name>/`
+ * directory) — composite runtime profiles like `core+skill-writer` have no
+ * file to write, so the caller resolves which part-profile to target before
+ * calling. Validates the id against the catalog and guards the profile name
+ * against path traversal. Idempotent: a no-op (alreadyPresent: true) when the
+ * id is already wired.
+ */
+export async function addMcpToProfile(id: string, profileName: string): Promise<AddMcpResult> {
+  if (!id || !loadAllMcpIds().includes(id)) {
+    throw new Error(`unknown-mcp: "${id}" is not in the cue catalog`);
+  }
+  // Reject anything that could escape profiles/ — names are flat slugs.
+  if (!/^[a-z0-9][a-z0-9_-]*$/i.test(profileName)) {
+    throw new Error(`invalid-profile: "${profileName}"`);
+  }
+  const dir = profilesDir();
+  const yamlPath = join(dir, profileName, "profile.yaml");
+  if (!resolve(yamlPath).startsWith(resolve(dir))) {
+    throw new Error(`invalid-profile: "${profileName}"`);
+  }
+  try {
+    await access(yamlPath);
+  } catch {
+    throw new Error(
+      `not-a-physical-profile: "${profileName}" has no profile.yaml (composite profiles can't be written directly)`,
+    );
+  }
+
+  let content = await readFile(yamlPath, "utf8");
+
+  // Already present? Match a list item exactly so "- gbrain" doesn't match
+  // "- gbrain-extra".
+  const present = content
+    .split("\n")
+    .some((l) => new RegExp(`^\\s*-\\s+${escapeRe(id)}\\s*(#.*)?$`).test(l));
+  if (present) return { id, profile: profileName, alreadyPresent: true };
+
+  if (/^mcps:/m.test(content)) {
+    const lines = content.split("\n");
+    const mcpsIdx = lines.findIndex((l) => /^mcps:/.test(l));
+    let insertIdx = mcpsIdx + 1;
+    while (insertIdx < lines.length && /^\s+-\s/.test(lines[insertIdx] ?? "")) insertIdx++;
+    lines.splice(insertIdx, 0, `  - ${id}`);
+    content = lines.join("\n");
+  } else {
+    content = content.trimEnd() + `\nmcps:\n  - ${id}\n`;
+  }
+
+  await writeFile(yamlPath, content);
+  return { id, profile: profileName, alreadyPresent: false };
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/lib/pair-suggestions.test.ts

@@ -1,10 +1,12 @@
 import { describe, expect, test } from "bun:test";
 
 import {
+  buildUniversalSuggestions,
   computeAffinityMap,
   parseComposite,
   suggestPartnersFor,
   suggestionsByProfile,
+  UNIVERSAL_COMPANIONS,
 } from "./pair-suggestions";
 
 const row = (profile: string, ts = "2026-05-28T00:00:00Z"): string =>
@@ -142,3 +144,112 @@ describe("suggestionsByProfile", () => {
     expect(all.get("solo")).toBeUndefined();
   });
 });
+
+describe("buildUniversalSuggestions", () => {
+  const known = (...names: string[]) => new Set(names);
+
+  test("featured come first in declared order, capped, and filtered to installed", () => {
+    const out = buildUniversalSuggestions({
+      featured: ["improver", "ghost", "secops", "builder", "maker", "studio", "ops"],
+      affinity: computeAffinityMap(lines()),
+      known: known("improver", "secops", "builder", "maker", "studio", "ops"),
+    });
+    // `ghost` dropped (not installed); default cap 5 keeps the first five real ones,
+    // so `ops` (sixth) is excluded.
+    expect(out).toEqual([
+      { name: "improver", origin: "featured" },
+      { name: "secops", origin: "featured" },
+      { name: "builder", origin: "featured" },
+      { name: "maker", origin: "featured" },
+      { name: "studio", origin: "featured" },
+    ]);
+  });
+
+  test("frequency fills the rest, highest picks first, above the floor", () => {
+    const affinity = computeAffinityMap(
+      lines(
+        ...Array(10).fill(row("skill-writer")),
+        ...Array(5).fill(row("core")),
+        ...Array(2).fill(row("rare")), // below default minFrequentPicks=3
+      ),
+    );
+    const out = buildUniversalSuggestions({
+      featured: [],
+      affinity,
+      known: known("skill-writer", "core", "rare"),
+    });
+    expect(out).toEqual([
+      { name: "skill-writer", origin: "frequent" },
+      { name: "core", origin: "frequent" },
+    ]);
+  });
+
+  test("a profile that is both featured and frequent appears once, as featured", () => {
+    const affinity = computeAffinityMap(lines(...Array(10).fill(row("improver"))));
+    const out = buildUniversalSuggestions({
+      featured: ["improver"],
+      affinity,
+      known: known("improver"),
+    });
+    expect(out).toEqual([{ name: "improver", origin: "featured" }]);
+  });
+
+  test("empty featured + empty history yields nothing", () => {
+    expect(
+      buildUniversalSuggestions({ featured: [], affinity: new Map(), known: new Set() }),
+    ).toEqual([]);
+  });
+
+  test("caps and the frequency floor are configurable", () => {
+    const affinity = computeAffinityMap(
+      lines(...Array(5).fill(row("a")), ...Array(4).fill(row("b")), ...Array(3).fill(row("c"))),
+    );
+    const out = buildUniversalSuggestions({
+      featured: ["f1", "f2"],
+      affinity,
+      known: known("f1", "f2", "a", "b", "c"),
+      maxFeatured: 1,
+      maxFrequent: 1,
+      minFrequentPicks: 4,
+    });
+    // featured cap 1 → f1; frequency cap 1 with floor 4 → a (5 picks, highest).
+    expect(out).toEqual([
+      { name: "f1", origin: "featured" },
+      { name: "a", origin: "frequent" },
+    ]);
+  });
+
+  test("pinned companions (gstack) close the list when installed, after featured/frequent", () => {
+    const gstack = UNIVERSAL_COMPANIONS[0]!; // "gstack"
+    const affinity = computeAffinityMap(lines(...Array(5).fill(row("a"))));
+    const out = buildUniversalSuggestions({
+      featured: ["f1"],
+      affinity,
+      known: known("f1", "a", gstack),
+    });
+    expect(out).toEqual([
+      { name: "f1", origin: "featured" },
+      { name: "a", origin: "frequent" },
+      { name: gstack, origin: "pinned" },
+    ]);
+  });
+
+  test("a pinned companion that isn't installed is silently dropped", () => {
+    const out = buildUniversalSuggestions({
+      featured: ["f1"],
+      affinity: new Map(),
+      known: known("f1"), // gstack not installed
+    });
+    expect(out).toEqual([{ name: "f1", origin: "featured" }]);
+  });
+
+  test("a pinned companion already in featured keeps its featured origin (de-duped)", () => {
+    const gstack = UNIVERSAL_COMPANIONS[0]!;
+    const out = buildUniversalSuggestions({
+      featured: [gstack],
+      affinity: new Map(),
+      known: known(gstack),
+    });
+    expect(out).toEqual([{ name: gstack, origin: "featured" }]);
+  });
+});

package/src/lib/pair-suggestions.ts

@@ -13,6 +13,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { readComboHistoryLines } from "./combo-history";
 
 /** Resolved path mirrors `lib/telemetry-consent` to avoid a circular import. */
 function sessionLogPath(): string {
@@ -159,12 +160,104 @@ export function suggestionsByProfile(
   return out;
 }
 
+/** Where a universal combine suggestion came from — drives the row hint. */
+export type UniversalOrigin = "featured" | "frequent" | "pinned";
+
+/** A cross-profile combine suggestion offered under every primary. */
+export interface UniversalSuggestion {
+  name: string;
+  origin: UniversalOrigin;
+}
+
+/**
+ * Profiles offered as a combine companion under *every* primary, independent of
+ * the curated featured set, session frequency, the picked profile's
+ * `recommends:`, or cwd content. gstack is the engineering-team layer (ship /
+ * QA / deploy / review) that pairs with whatever stack you're building, so the
+ * picker always offers to stack it on. Emitted as the `pinned` origin by
+ * `buildUniversalSuggestions` (the single "offered under every primary" path)
+ * and surfaced unchecked — offered, never forced into the pin.
+ */
+export const UNIVERSAL_COMPANIONS: readonly string[] = ["gstack"];
+
+export interface BuildUniversalOptions {
+  /** Curated featured slugs, in display order (from `_featured.yaml`). */
+  featured: string[];
+  /** Global pick-frequency map (from `computeAffinityMap`). */
+  affinity: Map<string, ProfileAffinity>;
+  /** Installed profile names — both sources are filtered to these. */
+  known: Set<string>;
+  /** Max curated featured suggestions. Default 5. */
+  maxFeatured?: number;
+  /** Max session-frequency suggestions. Default 2. */
+  maxFrequent?: number;
+  /** Min own-picks for a profile to count as "used a lot". Default 3. */
+  minFrequentPicks?: number;
+}
+
+const UNIVERSAL_DEFAULTS: Required<Omit<BuildUniversalOptions, "featured" | "affinity" | "known">> =
+  { maxFeatured: 5, maxFrequent: 2, minFrequentPicks: 3 };
+
+/**
+ * Cross-profile combine suggestions surfaced under *every* primary: the curated
+ * `_featured.yaml` set (where profiles like `improver` live) plus the profiles
+ * the user actually picks most often, mined from session history. Featured wins
+ * on overlap and ordering; frequency fills the remaining slots. Both are
+ * filtered to installed profiles and capped so the combine list stays short.
+ *
+ * Pure: the picker offers the result *unchecked* (a hint, never an auto-pin),
+ * de-duped against recommends/history/detected. Empty featured + empty affinity
+ * yields an empty list.
+ */
+export function buildUniversalSuggestions(opts: BuildUniversalOptions): UniversalSuggestion[] {
+  const o = { ...UNIVERSAL_DEFAULTS, ...opts };
+  const out: UniversalSuggestion[] = [];
+  const seen = new Set<string>();
+
+  // Curated featured first, in declared order, capped.
+  for (const name of o.featured) {
+    if (out.length >= o.maxFeatured) break;
+    if (seen.has(name) || !o.known.has(name)) continue;
+    seen.add(name);
+    out.push({ name, origin: "featured" });
+  }
+
+  // Frequency fills the rest: own-picks above the floor, highest first.
+  const frequent = [...o.affinity.entries()]
+    .filter(([name, a]) => o.known.has(name) && !seen.has(name) && a.picks >= o.minFrequentPicks)
+    .sort((x, y) => y[1].picks - x[1].picks || x[0].localeCompare(y[0]))
+    .slice(0, o.maxFrequent);
+  for (const [name] of frequent) {
+    seen.add(name);
+    out.push({ name, origin: "frequent" });
+  }
+
+  // Pinned companions (gstack) close the list: always offered under every
+  // primary, after featured/frequent so those keep their slots. De-duped (a
+  // pinned profile that's also featured keeps the earlier featured origin) and
+  // known-filtered like the rest, so an uninstalled pin silently drops.
+  for (const name of UNIVERSAL_COMPANIONS) {
+    if (seen.has(name) || !o.known.has(name)) continue;
+    seen.add(name);
+    out.push({ name, origin: "pinned" });
+  }
+
+  return out;
+}
+
 function defaultReadLines(): string[] {
+  const lines: string[] = [];
   const path = sessionLogPath();
-  if (!existsSync(path)) return [];
-  try {
-    return readFileSync(path, "utf8").split("\n");
-  } catch {
-    return [];
+  if (existsSync(path)) {
+    try {
+      lines.push(...readFileSync(path, "utf8").split("\n"));
+    } catch {
+      /* session log unreadable — fall through to combo history */
+    }
   }
+  // Combos picked in the interactive picker (combo-history.jsonl) share the
+  // `{profile}` row shape, so they fold straight into the affinity map. This is
+  // the telemetry-free source: it exists even when session logging is off.
+  lines.push(...readComboHistoryLines());
+  return lines;
 }