carthagent 1.0.7 → 1.1.0-preview.12

package/plugins/carthagent/src/ui/host-state.ts

@@ -0,0 +1,42 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export type NativeCliConfig = Record<string, unknown> & { theme?: { name?: string } | string };
+
+/** Resolve OpenCode's native CLI profile config (not CTG's separate user profile). */
+export function cliConfigPath(env = process.env, home = process.env.HOME ?? "") {
+  const configRoot = env.OPENCODE_CONFIG_DIR || join(env.XDG_CONFIG_HOME || join(home, ".config"), "opencode");
+  return join(configRoot, "cli.json");
+}
+
+/** Native TUI themes are discovered from config/opencode/themes for this profile. */
+export function cliConfigDirectory(env = process.env, home = process.env.HOME ?? "") {
+  return env.OPENCODE_CONFIG_DIR || join(env.XDG_CONFIG_HOME || join(home, ".config"), "opencode");
+}
+
+export async function readCliConfig(path: string): Promise<NativeCliConfig> {
+  try {
+    const value: unknown = JSON.parse(await readFile(path, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value) ? value as NativeCliConfig : {};
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+/** Atomically preserve unrelated native CLI settings while selecting a theme. */
+export async function writeNativeTheme(path: string, name: string) {
+  const config = await readCliConfig(path);
+  config.theme = typeof config.theme === "object" && config.theme !== null
+    ? { ...config.theme, name }
+    : { name };
+  await mkdir(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    await writeFile(temp, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    await rename(temp, path);
+  } catch (error) {
+    await import("node:fs/promises").then(({ rm }) => rm(temp, { force: true })).catch(() => undefined);
+    throw error;
+  }
+}

package/plugins/carthagent/src/ui/native-navigation.ts

@@ -0,0 +1,23 @@
+import type { Context } from "@opencode/plugin/tui/context";
+import type { JSX } from "solid-js";
+
+/** Optional host extension: released runtimes retain slash-command navigation. */
+export type NavigationInput = {
+  readonly width: number;
+  readonly compact: boolean;
+  readonly active: boolean;
+  readonly focused: boolean;
+  readonly sessionID?: string;
+  readonly focus: () => void;
+  readonly blur: () => void;
+};
+
+export type NativeNavigation = {
+  register(pane: { name: string; title: string; render(input: NavigationInput): JSX.Element }): () => void;
+  select(name: string): boolean;
+  current(): string;
+};
+
+export function nativeNavigation(context: Pick<Context, "ui">) {
+  return (context.ui as Context["ui"] & { navigation?: NativeNavigation }).navigation;
+}

package/plugins/carthagent/src/ui/native-review.d.mts

@@ -0,0 +1,31 @@
+export interface NativeReviewOffer {
+  sessionID: string;
+  runKey: string;
+  writes: number;
+  start: () => Promise<boolean>;
+}
+
+export interface NativeReviewConsumerOptions {
+  mode: (sessionID: string) => string;
+  diff: (sessionID: string, signal?: AbortSignal) => Promise<unknown>;
+  offer: (value: NativeReviewOffer) => Promise<unknown>;
+  kickoff: (sessionID: string, signal?: AbortSignal) => Promise<unknown>;
+  isLoopActive?: (sessionID: string) => boolean;
+  setLoopActive?: (sessionID: string, active: boolean) => void;
+  signal?: AbortSignal;
+}
+
+export function sendNativeReviewKickoff(options: { client: any; sessionID: string; signal?: AbortSignal; prompt?: string }): Promise<void>;
+export function nativeReviewMode(session: any, config: any, explicitMode?: string): string;
+export function createNativeReviewConsumer(options: NativeReviewConsumerOptions): {
+  setLoopActive(sessionID: string, active: boolean): void;
+  onUserPromptAdmitted(sessionID: string, message?: { type?: string; metadata?: Record<string, unknown> }): void;
+  onInboxDelivered(event: any, message?: { type?: string; metadata?: Record<string, unknown> }): void;
+  onStarted(event: any): void;
+  onSucceeded(event: any): Promise<void>;
+  onFailed(event: any): Promise<void>;
+  onInterrupted(event: any): Promise<void>;
+  enqueueInboxDelivery(event: any, getMessage: (sessionID: string, messageID: string, signal: AbortSignal) => Promise<{ type?: string; metadata?: Record<string, unknown> } | undefined>): Promise<void>;
+  dispose(): void;
+};
+export function subscribeNativeReviewEvents(data: any, consumer: ReturnType<typeof createNativeReviewConsumer>, onError?: (error: unknown) => void, getMessage?: (sessionID: string, messageID: string, signal: AbortSignal) => Promise<{ type?: string; metadata?: Record<string, unknown> } | undefined>): Array<() => void>;

package/plugins/carthagent/src/ui/native-review.mjs

@@ -0,0 +1,154 @@
+import { reviewKickoff } from "../../../../lib/review.mjs";
+import { resolveReviewMode } from "../../../../lib/review.mjs";
+import { SESSION_OPTIONS_KEY } from "../../../../lib/opencode/session-options.mjs";
+
+/** Send the PR ↔ fresh-review ↔ fixes instruction to the working session. */
+export async function sendNativeReviewKickoff({ client, sessionID, signal, prompt = reviewKickoff() }) {
+  await client.session.prompt({ sessionID, text: prompt, metadata: { "ctg.raw": true, "ctg.reviewKickoff": true } }, { signal });
+}
+
+/** Explicit launch mode persisted for the session wins over the profile default. */
+export function nativeReviewMode(session, config, explicitMode) {
+  return resolveReviewMode(explicitMode ?? session?.metadata?.[SESSION_OPTIONS_KEY]?.review, config);
+}
+
+/** Correlate host executions and admit one current-run kickoff per session. */
+/** @param {{ mode: (sessionID: string) => string, diff: (sessionID: string, signal?: AbortSignal) => Promise<unknown>, offer: (value: { sessionID: string; runKey: string; writes: number; start: () => Promise<boolean> }) => Promise<unknown>, kickoff: (sessionID: string, signal?: AbortSignal) => Promise<unknown>, isLoopActive?: (sessionID: string) => boolean, setLoopActive?: (sessionID: string, active: boolean) => void, signal?: AbortSignal }} options */
+export function createNativeReviewConsumer({ mode, diff, offer, kickoff, isLoopActive = () => false, setLoopActive = () => {}, signal }) {
+  const runs = new Map();
+  const admitted = new Set();
+  const pending = new Set();
+  const loopSessions = new Set();
+  const admissionTails = new Map();
+  const loopGenerations = new Map();
+  const admissionAbort = new AbortController();
+  let sequence = 0;
+  let disposed = false;
+
+  async function finish(sessionID, succeeded) {
+    const run = runs.get(sessionID);
+    if (!run || disposed) return;
+    // Inbox delivery follows execution.started and precedes the terminal event.
+    // Wait for the exact delivered message lookup before deciding whether the
+    // restored review loop still suppresses this run.
+    const admissionTail = admissionTails.get(sessionID);
+    try { await admissionTail; } catch {}
+    if (admissionTails.get(sessionID) === admissionTail) admissionTails.delete(sessionID);
+    if (disposed || runs.get(sessionID) !== run || run.finished) return;
+    run.finished = true;
+    if (!succeeded || signal?.aborted || loopSessions.has(sessionID) || isLoopActive(sessionID)) return;
+
+    let baseline;
+    try { baseline = await run.baseline; }
+    catch { return; }
+    if (disposed || signal?.aborted || runs.get(sessionID) !== run) return;
+    let changes;
+    try { changes = await diff(sessionID, signal); }
+    catch { return; }
+    if (disposed || signal?.aborted || runs.get(sessionID) !== run) return;
+    if (!Array.isArray(changes) || !Array.isArray(baseline)) return;
+    const before = new Map(baseline.map((file) => [file.file, `${file.status}\0${file.patch}`]));
+    const writes = changes.filter((file) => file && (file.additions > 0 || file.deletions > 0 || file.status === "added" || file.status === "deleted") && before.get(file.file) !== `${file.status}\0${file.patch}`).length;
+    const runKey = `${sessionID}@${run.id}`;
+    const currentMode = mode(sessionID);
+    if (!(currentMode === "ask" || currentMode === "yes") || writes <= 0 || admitted.has(runKey) || (currentMode === "yes" && loopSessions.has(sessionID))) return;
+    admitted.add(runKey);
+
+    const start = async () => {
+      if (disposed || signal?.aborted || runs.get(sessionID) !== run || pending.has(sessionID) || loopSessions.has(sessionID) || isLoopActive(sessionID)) return false;
+      pending.add(sessionID);
+      loopSessions.add(sessionID);
+      setLoopActive(sessionID, true);
+      try {
+        await kickoff(sessionID, signal);
+        return true;
+      } catch (error) {
+        loopSessions.delete(sessionID);
+        setLoopActive(sessionID, false);
+        throw error;
+      } finally {
+        pending.delete(sessionID);
+      }
+    };
+
+    if (currentMode === "yes") {
+      await start();
+      return;
+    }
+    let offered = false;
+    await offer({ sessionID, runKey, writes, start: async () => {
+      if (offered) return false;
+      offered = true;
+      if (runs.get(sessionID) !== run) return false;
+      return start();
+    } });
+  }
+
+  return {
+    onUserPromptAdmitted(sessionID, message, expectedGeneration) {
+      if (!sessionID || message?.type !== "user" || message.metadata?.["ctg.reviewKickoff"] === true) return;
+      if (expectedGeneration !== undefined && (loopGenerations.get(sessionID) ?? 0) !== expectedGeneration) return;
+      loopSessions.delete(sessionID);
+      if (isLoopActive(sessionID)) setLoopActive(sessionID, false);
+    },
+    setLoopActive(sessionID, active) {
+      if (!sessionID) return;
+      if (active) {
+        loopSessions.add(sessionID);
+        loopGenerations.set(sessionID, (loopGenerations.get(sessionID) ?? 0) + 1);
+      }
+      else loopSessions.delete(sessionID);
+      setLoopActive(sessionID, active);
+    },
+    onStarted(event) {
+      const sessionID = event?.data?.sessionID;
+      if (!sessionID || disposed) return;
+      const id = event.id ?? `${event.created ?? Date.now()}-${++sequence}`;
+      // A rejection is handled here, not left as an unhandled promise if the run fails.
+      const baseline = Promise.resolve().then(() => diff(sessionID, signal)).catch(() => undefined);
+      runs.set(sessionID, { id, baseline, finished: false });
+    },
+    onSucceeded(event) { return finish(event?.data?.sessionID, true); },
+    onFailed(event) { return finish(event?.data?.sessionID, false); },
+    onInterrupted(event) { return finish(event?.data?.sessionID, false); },
+    onInboxDelivered(event, message) {
+      const sessionID = event?.data?.sessionID;
+      if (!sessionID || disposed) return;
+      this.onUserPromptAdmitted(sessionID, message);
+    },
+    enqueueInboxDelivery(event, getMessage) {
+      const sessionID = event?.data?.sessionID;
+      const messageID = event?.data?.inboxID;
+      if (!sessionID || !messageID || disposed) return Promise.resolve();
+      const expectedGeneration = loopGenerations.get(sessionID) ?? 0;
+      const previous = admissionTails.get(sessionID) ?? Promise.resolve();
+      const current = previous.catch(() => {}).then(async () => {
+        if (disposed) return;
+        const timeout = AbortSignal.timeout(5_000);
+        const lookupSignal = signal ? AbortSignal.any([signal, admissionAbort.signal, timeout]) : AbortSignal.any([admissionAbort.signal, timeout]);
+        lookupSignal.throwIfAborted();
+        const message = await Promise.race([
+          getMessage(sessionID, messageID, lookupSignal),
+          new Promise((resolve) => lookupSignal.addEventListener("abort", () => resolve(undefined), { once: true })),
+        ]);
+        if (!disposed && !lookupSignal.aborted) this.onUserPromptAdmitted(sessionID, message, expectedGeneration);
+      });
+      admissionTails.set(sessionID, current);
+      return current;
+    },
+    dispose() { disposed = true; admissionAbort.abort(); admissionTails.clear(); runs.clear(); pending.clear(); },
+  };
+}
+
+/** Wire host admission and execution events; returned disposers belong to plugin setup. */
+export function subscribeNativeReviewEvents(data, consumer, onError = (_error) => {}, getMessage = async () => undefined) {
+  return [
+    data.on("session.inbox.delivered", (event) => {
+      return consumer.enqueueInboxDelivery(event, getMessage).catch(onError);
+    }),
+    data.on("session.execution.started", (event) => consumer.onStarted(event)),
+    data.on("session.execution.succeeded", (event) => consumer.onSucceeded(event).catch(onError)),
+    data.on("session.execution.failed", (event) => consumer.onFailed(event).catch(onError)),
+    data.on("session.execution.interrupted", (event) => consumer.onInterrupted(event).catch(onError)),
+  ];
+}

package/plugins/carthagent/src/ui/resume-session.mjs

@@ -0,0 +1,34 @@
+/** Resolve session IDs independently of the host's title-oriented search filter. */
+export async function findNativeResumeSession({ query, directory, client, pageSize = 100 }) {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) return undefined;
+  const isSessionID = /^ses(?:sion)?[_-]/i.test(query.trim());
+
+  if (isSessionID) {
+    try {
+      const exact = await client.session.get({ sessionID: query.trim() });
+      if (exact && !exact.parentID && exact.location.directory === directory) return exact;
+    } catch { /* non-exact IDs continue as prefix search */ }
+  }
+
+  const loadPages = async (search) => {
+    const sessions = [];
+    let cursor;
+    do {
+      const page = await client.session.list({
+        limit: pageSize, order: 'desc', directory,
+        ...(cursor ? { cursor } : {}), ...(search ? { search } : {}),
+      });
+      sessions.push(...page.data.filter((session) => !session.parentID));
+      cursor = page.cursor.next ?? undefined;
+    } while (cursor);
+    return sessions;
+  };
+
+  const unfiltered = await loadPages();
+  if (isSessionID) {
+    const prefix = unfiltered.find((session) => session.id.toLowerCase().startsWith(normalized));
+    if (prefix) return prefix;
+  }
+  return (await loadPages(query)).find((session) => (session.title ?? '').toLowerCase().includes(normalized));
+}

package/plugins/carthagent/src/ui/session-preferences.d.mts

@@ -0,0 +1,7 @@
+import type { JsonValue } from "@opencode/client";
+export type AutoCompactionAction = "on" | "off" | "toggle";
+export interface SessionMetadataClient {
+  get(input: { sessionID: string }, options: { location: unknown; signal: AbortSignal }): Promise<{ metadata?: Record<string, JsonValue> }>;
+  update(input: { sessionID: string; metadata: Record<string, JsonValue> }, options: { location: unknown; signal: AbortSignal }): Promise<unknown>;
+}
+export function setSessionAutoCompaction(client: SessionMetadataClient, sessionID: string, location: unknown, action: AutoCompactionAction): Promise<boolean>;

package/plugins/carthagent/src/ui/session-preferences.mjs

@@ -0,0 +1,14 @@
+/** Persist the host-owned per-session opt-out without disturbing neighbor metadata. */
+export async function setSessionAutoCompaction(client, sessionID, location, action) {
+  if (action !== "toggle" && action !== "on" && action !== "off") throw new TypeError("Usage: /autocompact [on|off].");
+  const options = { location, signal: AbortSignal.timeout(15_000) };
+  const session = await client.get({ sessionID }, options);
+  const metadata = { ...session.metadata };
+  const enabled = metadata["ctg.autoCompaction"] !== false;
+  const next = action === "on" ? true : action === "off" ? false : !enabled;
+  if (next === enabled) return enabled;
+  if (next) delete metadata["ctg.autoCompaction"];
+  else metadata["ctg.autoCompaction"] = false;
+  await client.update({ sessionID, metadata }, { location, signal: AbortSignal.timeout(15_000) });
+  return next;
+}

package/plugins/carthagent/src/ui/theme-provision.d.mts

@@ -0,0 +1,3 @@
+export declare function convertLegacyTheme(name: string, palette: Record<string, unknown>, lightPalette?: Record<string, unknown>): Record<string, unknown>;
+export declare function provisionNativeThemes(profileConfigDir: string, names?: readonly string[]): Promise<{ directory: string; installed: string[] }>;
+export declare function provisionDefaultNativeTheme(profileConfigDir: string): Promise<{ directory: string; installed: string[] }>;

package/plugins/carthagent/src/ui/theme-provision.mjs

@@ -0,0 +1,134 @@
+import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { flattenTheme, THEMES } from "../../../../lib/tui/theme.mjs";
+
+const PACKAGE_ROOT = fileURLToPath(new URL("../..", import.meta.url));
+const COLORS = ["red", "orange", "yellow", "green", "cyan", "blue", "purple", "gray"];
+const STEPS = [100, 200, 300, 400, 500, 600, 700, 800, 900];
+
+function mixHex(color, target, amount) {
+  const expand = (value) => {
+    const hex = value.slice(1);
+    const full = hex.length === 3 ? [...hex].map((digit) => digit + digit).join("") : hex;
+    return full.match(/[\da-f]{2}/gi)?.map((part) => Number.parseInt(part, 16)) ?? [128, 128, 128];
+  };
+  const source = expand(color);
+  const destination = expand(target);
+  return `#${source.map((channel, index) => Math.round(channel * (1 - amount) + destination[index] * amount).toString(16).padStart(2, "0")).join("")}`;
+}
+
+function buildPalette(palette) {
+  const fallback = "#808080";
+  const semantic = { red: palette.error, orange: palette.warning, yellow: palette.warning, green: palette.success, cyan: palette.info, blue: palette.info, purple: palette.primary ?? palette.secondary, gray: palette.textMuted };
+  const darkMode = Number.parseInt(palette.background?.slice(1, 3) ?? "80", 16) < 128;
+  const hue = Object.fromEntries(COLORS.map((color) => {
+    const source = typeof semantic[color] === "string" && /^#[\da-f]{6}$/i.test(semantic[color]) ? semantic[color] : fallback;
+    const scale = Object.fromEntries(STEPS.map((step) => {
+      const progress = (step - 100) / 800;
+      const towardLight = darkMode ? progress < 0.5 : progress >= 0.5;
+      const distance = Math.abs(progress - 0.5) / 0.5;
+      const amount = 0.78 * distance;
+      return [step, mixHex(source, towardLight ? "#ffffff" : "#000000", amount)];
+    }));
+    return [color, scale];
+  }));
+  hue.accent = "$hue.purple";
+  hue.interactive = "$hue.purple";
+  hue.neutral = "$hue.gray";
+  const token = (value) => {
+    if (typeof value !== "string" || !/^#[\da-f]{3,8}$/i.test(value)) return value;
+    return value;
+  };
+  const state = (base) => ({ base: token(base), $hovered: token(base), $pressed: token(base), $focused: token(base), $selected: token(base), $disabled: token(base) });
+  const feedback = (base) => ({ base: token(base), muted: token(base) });
+  return {
+    hue,
+    text: {
+      base: token(palette.text), muted: token(palette.textMuted), faint: token(palette.textMuted),
+      action: { primary: state(palette.primary), secondary: state(palette.secondary), destructive: state(palette.error) },
+      formfield: state(palette.text),
+      feedback: { info: feedback(palette.info), success: feedback(palette.success), warning: feedback(palette.warning), error: feedback(palette.error) },
+    },
+    background: {
+      base: token(palette.background),
+      raised: { base: token(palette.backgroundPanel), high: token(palette.backgroundElement), max: token(palette.border) },
+      action: { primary: state(palette.accent), secondary: state(palette.backgroundElement), destructive: state(palette.error) },
+      formfield: state(palette.background),
+      feedback: { info: { base: token(palette.info) }, success: { base: token(palette.success) }, warning: { base: token(palette.warning) }, error: { base: token(palette.error) } },
+    },
+    border: { base: token(palette.border) }, scrollbar: { base: token(palette.borderActive ?? palette.accent) },
+    diff: {
+      text: { added: token(palette.diffAdded), removed: token(palette.diffRemoved), context: token(palette.diffContext), hunkHeader: token(palette.diffHunkHeader) },
+      background: { added: token(palette.diffAddedBg), removed: token(palette.diffRemovedBg), context: token(palette.diffContextBg) },
+      highlight: { added: token(palette.diffHighlightAdded), removed: token(palette.diffHighlightRemoved) },
+      lineNumber: { text: token(palette.diffLineNumber), background: { added: token(palette.diffAddedLineNumberBg), removed: token(palette.diffRemovedLineNumberBg) } },
+    },
+    syntax: { comment: token(palette.syntaxComment), keyword: token(palette.syntaxKeyword), function: token(palette.syntaxFunction), variable: token(palette.syntaxVariable), string: token(palette.syntaxString), number: token(palette.syntaxNumber), type: token(palette.syntaxType), operator: token(palette.syntaxOperator), punctuation: token(palette.syntaxPunctuation) },
+    markdown: { text: token(palette.markdownText), heading: token(palette.markdownHeading), link: token(palette.markdownLink), linkText: token(palette.markdownLinkText), code: token(palette.markdownCode), blockQuote: token(palette.markdownBlockQuote), emphasis: token(palette.markdownEmph), strong: token(palette.markdownStrong), horizontalRule: token(palette.markdownHorizontalRule), listItem: token(palette.markdownListItem), listEnumeration: token(palette.markdownListEnumeration), image: token(palette.markdownImage), imageText: token(palette.markdownImageText), codeBlock: token(palette.markdownCodeBlock) },
+  };
+}
+
+/** Convert a legacy flat semantic palette into OpenCode's native theme JSON. */
+export function convertLegacyTheme(name, palette, lightPalette) {
+  const dark = buildPalette(palette);
+  const light = lightPalette ? buildPalette(lightPalette) : undefined;
+  const { hue: darkHue, ...base } = dark;
+  const lightHue = light?.hue ?? (name === "paper" || name.includes("light") ? darkHue : undefined);
+  return {
+    $schema: "https://opencode.ai/theme.json",
+    base: { ...base, categorical: ["accent", "purple", "cyan", "green", "blue"] },
+    dark: { hue: darkHue },
+    ...(lightHue ? { light: { hue: lightHue } } : {}),
+  };
+}
+
+/** Copy selected Carthagent compatibility themes into one OpenCode profile. */
+export async function provisionNativeThemes(profileConfigDir, names = Object.keys(THEMES)) {
+  const destination = join(profileConfigDir, "themes");
+  await mkdir(destination, { recursive: true });
+  const installed = [];
+  for (const name of names) {
+    const source = THEMES[name];
+    if (!source) throw new Error(`Unknown Carthagent theme: ${name}`);
+    const path = join(destination, `${name}.json`);
+    let exists = false;
+    try {
+      const existing = JSON.parse(await readFile(path, "utf8"));
+      exists = true;
+      if (existing.$schema === "https://opencode.ai/theme.json" && existing.dark) continue;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    if (exists) throw new Error(`Refusing to replace a non-native theme at ${path}`);
+    const document = name === "carthage"
+      ? JSON.parse(await readFile(join(PACKAGE_ROOT, "themes", "carthage.json"), "utf8"))
+      : convertLegacyTheme(name, flattenTheme(source, "dark"), ["solarized", "okabe", "contrast", "system"].includes(name) ? flattenTheme(source, "light") : undefined);
+    const temp = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    try {
+      await writeFile(temp, `${JSON.stringify(document, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+      await copyFile(temp, path, 1);
+      await rm(temp, { force: true });
+    } catch (error) {
+      await import("node:fs/promises").then(({ rm }) => rm(temp, { force: true })).catch(() => undefined);
+      throw error;
+    }
+    installed.push(name);
+  }
+  return { directory: destination, installed };
+}
+
+/** Launcher hook: install Carthagent's default theme before OpenCode scans themes. */
+export async function provisionDefaultNativeTheme(profileConfigDir) {
+  const compatibilityNames = Object.keys(THEMES).filter((name) => !["opencode", "tokyonight"].includes(name));
+  const installed = [];
+  const conflicts = [];
+  for (const name of compatibilityNames) {
+    try { installed.push(...(await provisionNativeThemes(profileConfigDir, [name])).installed); }
+    catch (error) {
+      if (!error.message.startsWith("Refusing to replace a non-native theme at ")) throw error;
+      conflicts.push(name);
+    }
+  }
+  return { directory: join(profileConfigDir, "themes"), installed, conflicts };
+}

package/plugins/carthagent/src/ui/voyages-navigation-state.mjs

@@ -0,0 +1,56 @@
+import { voyagesErrorCode } from './voyages-state.mjs';
+
+/** Read-only summaries only. Never retain recovery payloads, catalog or consent. */
+export function createVoyagesNavigationState({ profile, daily, changed = (_state) => {}, timeoutSignal = () => AbortSignal.timeout(15_000) }) {
+  let generation = 0, active = false, disposed = false;
+  let request = new AbortController();
+  let state = { busy: false, error: '', profile: undefined, daily: undefined };
+  const emit = () => { if (!disposed) changed({ ...state }); };
+  const invalidate = () => {
+    generation++;
+    request.abort();
+    request = new AbortController();
+    state = { busy: false, error: '', profile: undefined, daily: undefined };
+    emit();
+  };
+  const refresh = async () => {
+    if (disposed || !active || state.busy) return;
+    const current = generation;
+    const signal = AbortSignal.any([request.signal, timeoutSignal()]);
+    const live = () => !disposed && active && generation === current && !signal.aborted;
+    state = { busy: true, error: '', profile: undefined, daily: undefined };
+    emit();
+    try {
+      const [account, assignments] = await Promise.all([profile(signal), daily(signal)]);
+      if (!live()) return;
+      state.profile = {
+        name: account.profile.name, shipName: account.profile.shipName,
+        coins: account.profile.coins, level: account.profile.level, totalXp: account.profile.totalXp,
+      };
+      state.daily = {
+        day: assignments.slate.day, endsAt: assignments.slate.endsAt,
+        items: assignments.slate.items.map((quest) => ({ id: quest.id, title: quest.definition.title, status: quest.status })),
+      };
+    } catch (error) {
+      if (!disposed && active && generation === current) {
+        const code = error?.type === 'dailyQuestError' ? error.data?.code : voyagesErrorCode(error);
+        state.error = typeof code === 'string' && /^[a-z_]{1,64}$/.test(code) ? code : 'voyages_request_failed';
+      }
+    } finally {
+      if (!disposed && active && generation === current) { state.busy = false; emit(); }
+    }
+  };
+  return {
+    refresh,
+    invalidate,
+    activate(next) {
+      if (disposed || active === next) return;
+      active = next;
+      invalidate();
+      if (active) return refresh();
+    },
+    contextChanged() { invalidate(); if (active) return refresh(); },
+    disconnect() { invalidate(); },
+    dispose() { active = false; invalidate(); disposed = true; request.abort(); },
+  };
+}

package/plugins/carthagent/src/ui/voyages-navigation.tsx

@@ -0,0 +1,122 @@
+/** @jsxImportSource @opentui/solid */
+import { Show, createEffect, createSignal, onCleanup, onMount } from "solid-js";
+import { CliRenderEvents, type ScrollBoxRenderable, type SelectRenderable } from "@opentui/core";
+import { useRenderer } from "@opentui/solid";
+import { usePlugin } from "@opencode/plugin/tui";
+import { dailyQuestsClient, voyagesClient } from "./client.js";
+import { nativeNavigation, type NavigationInput } from "./native-navigation.js";
+import { createVoyagesNavigationState } from "./voyages-navigation-state.mjs";
+import { voyagesEventAction } from "./voyages-state.mjs";
+
+type Summary = {
+  busy: boolean; error: string;
+  profile?: { name: string; shipName: string; coins: number; level: number; totalXp: number };
+  daily?: { day: string; endsAt: string; items: { id: string; title: string; status: string }[] };
+};
+
+export function VoyagesNavigation(props: NavigationInput) {
+  const context = usePlugin();
+  const renderer = useRenderer();
+  const location = () => (props.sessionID ? context.data.session.get(props.sessionID)?.location : undefined) ?? context.location ?? context.data.location.default();
+  const [view, setView] = createSignal<Summary>({ busy: false, error: "" });
+  const [selection, setSelection] = createSignal("daily");
+  const profile = voyagesClient(context, location), daily = dailyQuestsClient(context, location);
+  const controller = createVoyagesNavigationState({ profile: profile.snapshot, daily: daily.snapshot, changed: setView });
+  let actions: SelectRenderable | undefined;
+  let scroll: ScrollBoxRenderable | undefined;
+  let scrollTop = 0;
+  let restoreTop: number | undefined;
+  const [viewportHeight, setViewportHeight] = createSignal(3);
+  createEffect(() => {
+    if (!props.active) { scrollTop = scroll?.scrollTop ?? scrollTop; return; }
+    if (!view().busy) { restoreTop = scrollTop; renderer.requestRender(); }
+  });
+  createEffect(() => { void controller.activate(props.active); });
+  let binding = JSON.stringify(location());
+  const resetSelection = () => { actions?.setSelectedIndex(0); setSelection("daily"); };
+  createEffect(() => {
+    const next = JSON.stringify(location());
+    if (binding === next) return;
+    binding = next;
+    resetSelection();
+    void controller.contextChanged();
+  });
+  onMount(() => {
+    // FRAME follows layout. Earlier restoration clamps to the loading extent.
+    const frame = () => {
+      if (!scroll || scroll.isDestroyed || !props.active) return;
+      setViewportHeight(Math.max(1, scroll.viewport.height));
+      if (restoreTop === undefined || view().busy) return;
+      scroll.scrollTop = restoreTop;
+      restoreTop = undefined;
+    };
+    renderer.on(CliRenderEvents.FRAME, frame);
+    onCleanup(() => renderer.off(CliRenderEvents.FRAME, frame));
+    const stop = context.data.listen(({ details }) => {
+      const changedLocation = binding !== JSON.stringify(location());
+      binding = JSON.stringify(location());
+      const action = changedLocation ? String(details.type) === "server.disconnected" ? "clear" : "refresh" : voyagesEventAction(details, location());
+      if (action === "ignore") return;
+      resetSelection();
+      if (action === "clear") controller.disconnect();
+      else void controller.contextChanged();
+    });
+    onCleanup(stop);
+  });
+  onCleanup(() => controller.dispose());
+  const open = (name: "voyages" | "daily-quests", extra: Record<string, string> = {}) => {
+    props.blur();
+    if (nativeNavigation(context)?.current() !== "voyages") return;
+    context.ui.router.navigate({ type: "plugin", name, data: { ...(props.sessionID ? { sessionID: props.sessionID } : {}), ...extra } });
+  };
+  const options = () => [
+    { name: props.compact ? "Q" : "Daily coding quests", description: "Assignments & assessments", value: "daily" },
+    ...(view().daily?.items.map((quest, index) => ({ name: props.compact ? String(index + 1) : quest.title, description: quest.status, value: `quest:${quest.id}` })) ?? []),
+    { name: props.compact ? "P" : "Profile & wallet", description: "Authoritative profile", value: "profile" },
+    { name: props.compact ? "E" : "Equipment & shop", description: "Preview before any purchase", value: "equipment" },
+    { name: props.compact ? "R" : "Refresh summaries", description: "Read-only; no evidence upload", value: "refresh" },
+    { name: props.compact ? "S" : "Sign in / reconnect", description: "Native Ship device sign-in", value: "signin" },
+    { name: props.compact ? "B" : "Return to coding", description: "Keep the selected session", value: "back" },
+  ];
+  const select = (value?: string) => {
+    if (!props.active || context.keymap.mode.current() !== "navigation" || !props.focused || !value) return;
+    if (value === "refresh") { void controller.refresh(); return; }
+    if (value === "signin") { controller.invalidate(); props.blur(); context.keymap.dispatch("provider.connect"); return; }
+    if (value === "back") {
+      props.blur();
+      nativeNavigation(context)?.select("projects");
+      context.ui.router.navigate(props.sessionID ? { type: "session", sessionID: props.sessionID } : { type: "home" });
+      return;
+    }
+    if (value === "profile" || value === "equipment") { open("voyages", { section: value }); return; }
+    open("daily-quests", value.startsWith("quest:") ? { questID: value.slice(6) } : {});
+  };
+  const focused = () => props.active && props.focused && context.keymap.mode.current() === "navigation";
+  return <box flexDirection="column" flexGrow={1} minHeight={0} onMouseDown={() => { if (props.active && context.keymap.mode.current() === "base") props.focus(); }}>
+    <scrollbox ref={scroll} flexGrow={1} minHeight={0} contentOptions={{ flexDirection: "column" }}>
+      <Show when={!props.compact}>
+        <Show when={view().profile}>{(p) => <box flexDirection="column" flexShrink={0} paddingX={1}>
+          <text fg={context.theme.text.base}>{p().name}</text>
+          <text fg={context.theme.text.muted}>{p().shipName}</text>
+          <text fg={context.theme.text.action.primary.base}>Lv {p().level} · {p().coins} coins</text>
+          <text fg={context.theme.text.muted}>XP {p().totalXp}</text>
+        </box>}</Show>
+        <Show when={view().busy}><text flexShrink={0} fg={context.theme.text.muted}> Loading summaries…</text></Show>
+        <Show when={view().error}><text flexShrink={0} fg={context.theme.text.feedback.warning.base}> {view().error}. Sign in or refresh.</text></Show>
+        <Show when={view().daily}><text flexShrink={0} fg={context.theme.text.muted}> UTC {view().daily?.day}</text></Show>
+      </Show>
+      <select ref={actions} minHeight={1} height={Math.min(18, viewportHeight(), options().length * (props.compact ? 1 : 2))} flexShrink={0} showScrollIndicator showDescription={!props.compact} options={options()} selectedIndex={Math.max(0, options().findIndex((item) => item.value === selection()))} focused={focused()} onChange={(_index, item) => {
+        if (!focused() || view().busy || !item) return;
+        setSelection(item.value);
+        if (actions) scroll?.scrollChildIntoView(actions.id);
+      }} onSelect={(_index, item) => select(item?.value)} />
+      <Show when={!props.compact}>
+        <text flexShrink={0} fg={context.theme.text.faint}> Badges & friends: no native views yet.</text>
+        <text flexShrink={0} fg={context.theme.text.faint}> Quests: no rewards. No automatic uploads.</text>
+      </Show>
+    </scrollbox>
+    <Show when={!props.compact}>
+      <text flexShrink={0} fg={context.theme.text.faint}>{focused() ? " ↑/↓ Enter · Esc coding" : " Focus pane to navigate"}</text>
+    </Show>
+  </box>;
+}