mini-coder 0.5.8 → 0.5.10

package/README.md

@@ -103,7 +103,7 @@ $ printf '%s\n' 'fix the failing tests' | mc
 - Starts when `-p/--prompt` is provided or when stdin or stdout is not a TTY.
 - If stdout is redirected but stdin is still interactive, pass `-p`; headless mode will not fall back to an interactive prompt.
 - Uses the same parser as the TUI for plain text, `/skill:name`, and standalone image paths.
-- With `--json`, writes NDJSON events for completed assistant/tool-result messages plus `done` / `error` / `aborted` outcomes; streaming deltas are omitted.
+- With `--json`, writes NDJSON events for completed assistant/tool-result messages plus `done` / `error` / `aborted` outcomes; queued `user_message` events may also appear. Streaming deltas are omitted.
 - Headless runs still persist like normal sessions and show up in `/session` history for that working directory.
 - Interactive slash commands such as `/model`, `/session`, and `/help` are not available in headless mode.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mini-coder",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "A small, fast CLI coding agent",
   "module": "src/index.ts",
   "type": "module",

package/src/input.ts

@@ -17,7 +17,6 @@ import { extname, isAbsolute, join } from "node:path";
 
 /** All recognized slash commands. */
 export const COMMANDS = [
-  "model",
   "session",
   "new",
   "fork",
@@ -28,6 +27,7 @@ export const COMMANDS = [
   "login",
   "logout",
   "help",
+  "model",
   "effort",
 ] as const;
 

package/src/prompt.ts

@@ -246,6 +246,7 @@ function buildCorePrompt(opts: BuildSystemPromptOpts): string {
     "- Check requirements, and plan your changes before editing code.",
     "- Implement the necessary changes, following good practices and proper error handling.",
     "- Always verify your changes using compilation, testing, and manual verification when possible.",
+    "- When verifying with build or test commands, avoid leaving generated binaries or scratch artifacts in the requested output location; use temporary paths or remove them before finishing.",
     "- Do not leave helpers, tests, or any other form of temporary files; clean up after yourself and leave no trace.",
     "- Ensure you match the requested output exactly. This applies to file names, directory structure, number of files, output formats, and all other details.",
     '- "Polish" is not optional; it counts just as much as solving the task.',

package/src/session.ts

@@ -95,6 +95,9 @@ interface AppendPromptHistoryOpts {
   sessionId?: string;
 }
 
+/** Rich-text format hints supported by persisted UI info messages. */
+export type UiInfoFormat = "markdown";
+
 /** A persisted UI-only info message shown in the conversation log. */
 export interface UiInfoMessage {
   /** Identifies this as an internal UI message. */
@@ -103,6 +106,8 @@ export interface UiInfoMessage {
   kind: "info";
   /** Display text shown in the conversation log. */
   content: string;
+  /** Optional rich-text format hint for the content. */
+  format?: UiInfoFormat;
   /** Unix timestamp in milliseconds. */
   timestamp: number;
 }
@@ -513,7 +518,10 @@ function isUiMessageRecord(value: unknown): value is UiMessage {
   }
 
   if (record.kind === "info") {
-    return typeof record.content === "string";
+    return (
+      typeof record.content === "string" &&
+      (record.format === undefined || record.format === "markdown")
+    );
   }
 
   return (
@@ -629,13 +637,18 @@ export function truncateSessions(
  * Create a persisted UI info message.
  *
  * @param content - Display text shown in the conversation log.
+ * @param format - Optional rich-text format hint for the content.
  * @returns A new {@link UiInfoMessage}.
  */
-export function createUiMessage(content: string): UiInfoMessage {
+export function createUiMessage(
+  content: string,
+  format?: UiInfoFormat,
+): UiInfoMessage {
   return {
     role: "ui",
     kind: "info",
     content,
+    ...(format ? { format } : {}),
     timestamp: Date.now(),
   };
 }

package/src/tools.ts

@@ -1574,7 +1574,8 @@ export const shellTool: Tool = {
   name: "shell",
   description:
     "Run a command in the user's shell. Returns stdout, stderr, and exit code. " +
-    "Use this to explore the codebase, read tests/verifiers/examples, inspect required outputs, and run targeted checks, builds, or git commands.",
+    "Use this to explore the codebase, read tests/verifiers/examples, inspect required outputs, and run targeted checks, builds, or git commands. " +
+    "Commands mutate the real working directory, so direct verification outputs to temporary paths or clean them up before finishing.",
   parameters: Type.Object({
     command: Type.String({ description: "The shell command to execute" }),
   }),

package/src/ui/commands.test.ts

@@ -520,6 +520,44 @@ describe("ui/commands", () => {
     }
   });
 
+  test("/help appends markdown help without creating a session", () => {
+    const state = createTestState();
+    const appended: Array<{
+      text: string;
+      format: string | undefined;
+      sessionId: string | null;
+    }> = [];
+    const controller = createCommandController({
+      openOverlay: () => {},
+      dismissOverlay: () => {},
+      setInputValue: () => {},
+      appendInfoMessage: (text, nextState, format) => {
+        appended.push({
+          text,
+          format,
+          sessionId: nextState.session?.id ?? null,
+        });
+      },
+      appendTodoMessage: () => {},
+      scrollConversationToBottom: () => {},
+      render: () => {},
+      reloadPromptContext: async () => {},
+      openInBrowser: () => {},
+    });
+
+    try {
+      expect(controller.handleCommand("help", state)).toBe(true);
+      expect(appended).toHaveLength(1);
+      expect(appended[0]?.text).toContain("# Help");
+      expect(appended[0]?.text).toContain("## Commands");
+      expect(appended[0]?.format).toBe("markdown");
+      expect(appended[0]?.sessionId).toBeNull();
+      expect(state.session).toBeNull();
+    } finally {
+      state.db.close();
+    }
+  });
+
   test("/todo appends the current todo list without creating a session", () => {
     const state = createTestState();
     state.messages = [

package/src/ui/commands.ts

@@ -26,6 +26,7 @@ import {
   listSessions,
   loadMessages,
   type SessionListEntry,
+  type UiInfoFormat,
   undoLastTurn,
 } from "../session.ts";
 import { updateSettings } from "../settings.ts";
@@ -51,7 +52,11 @@ interface UiCommandRuntime {
   /** Update the current input draft. */
   setInputValue: (value: string) => void;
   /** Append a UI-only info message to the conversation log. */
-  appendInfoMessage: (text: string, state: AppState) => void;
+  appendInfoMessage: (
+    text: string,
+    state: AppState,
+    format?: UiInfoFormat,
+  ) => void;
   /** Append a UI-only todo snapshot to the conversation log. */
   appendTodoMessage: (
     todos: ReturnType<typeof getTodoItems>,
@@ -583,7 +588,7 @@ export function createCommandController(
   };
 
   const handleHelpCommand = (state: AppState): void => {
-    runtime.appendInfoMessage(buildHelpText(state), state);
+    runtime.appendInfoMessage(buildHelpText(state), state, "markdown");
   };
 
   const handleTodoCommand = (state: AppState): void => {

package/src/ui/conversation.test.ts

@@ -1372,6 +1372,57 @@ describe("ui/conversation", () => {
     expect(text.some((line) => line.startsWith("And "))).toBe(false);
   });
 
+  test("buildConversationLogNodes syntax-highlights markdown-formatted UI info messages", async () => {
+    const theme = {
+      ...DEFAULT_THEME,
+      accentText: "color14",
+      secondaryAccentText: "color09",
+      diffAdded: "color10",
+    } satisfies typeof DEFAULT_THEME;
+    const state = {
+      messages: [
+        {
+          role: "ui" as const,
+          kind: "info" as const,
+          format: "markdown" as const,
+          content: "# Help\n\n## Commands\n\n- `/model` — Select a model",
+          timestamp: 1,
+        },
+      ],
+      showReasoning: false,
+      verbose: false,
+      theme,
+    };
+
+    const rows = await renderBufferRows(
+      VStack(
+        {},
+        buildConversationLogNodes(
+          state,
+          { isStreaming: false, content: [], pendingToolResults: [] },
+          0,
+          PREVIEW_WIDTH,
+        ),
+      ),
+      PREVIEW_WIDTH,
+      24,
+    );
+    const headingRow = rows.find((row) => row.text.includes("# Help"));
+    const bulletRow = rows.find((row) => row.text.includes("- `/model`"));
+
+    expect(headingRow).toBeDefined();
+    expect(bulletRow).toBeDefined();
+    expect(headingRow?.fgColors[headingRow.text.indexOf("#")]).toBe(
+      theme.accentText ?? null,
+    );
+    expect(bulletRow?.fgColors[bulletRow.text.indexOf("-")]).toBe(
+      theme.secondaryAccentText ?? null,
+    );
+    expect(bulletRow?.fgColors[bulletRow.text.indexOf("`")]).toBe(
+      theme.diffAdded ?? null,
+    );
+  });
+
   test("buildConversationLogNodes renders UI todo messages with the shared checklist block", async () => {
     const state = {
       messages: [

package/src/ui/conversation.ts

@@ -1161,14 +1161,28 @@ function renderUiTodoMessage(
 }
 
 /** Render an internal UI message in the conversation log. */
-function renderUiMessage(msg: UiMessage, theme: Theme): Node {
+function renderUiMessage(
+  msg: UiMessage,
+  opts: Pick<ConversationRenderOpts, "previewWidth" | "theme">,
+): Node {
   if (msg.kind === "todo") {
-    return renderUiTodoMessage(msg, theme);
+    return renderUiTodoMessage(msg, opts.theme);
+  }
+
+  if (msg.format === "markdown") {
+    const markdown = renderMarkdownTextBlock(
+      msg.content,
+      opts.theme,
+      opts.previewWidth,
+    );
+    if (markdown) {
+      return markdown;
+    }
   }
 
   return VStack({ padding: { x: 1 } }, [
     Text(msg.content, {
-      fgColor: theme.mutedText,
+      fgColor: opts.theme.mutedText,
       italic: true,
       wrap: "word",
     }),
@@ -1231,7 +1245,7 @@ function renderConversationMessage(
   theme: Theme,
 ): Node | null {
   if (message.role === "ui") {
-    return renderUiMessage(message, theme);
+    return renderUiMessage(message, renderOpts);
   }
   if (message.role === "user") {
     return renderUserMessage(message, theme);

package/src/ui/help.test.ts

@@ -3,7 +3,7 @@ import { DEFAULT_SHOW_REASONING } from "../settings.ts";
 import { buildHelpText, type HelpRenderState } from "./help.ts";
 
 describe("ui/help", () => {
-  test("buildHelpText includes current reasoning and verbose state", () => {
+  test("buildHelpText formats commands as markdown list items with current state", () => {
     const helpState: HelpRenderState = {
       providers: new Map(),
       model: null,
@@ -16,16 +16,18 @@ describe("ui/help", () => {
 
     const text = buildHelpText(helpState);
 
+    expect(text).toContain("# Help");
+    expect(text).toContain("## Commands");
     expect(text).toContain(
-      `/reasoning  Toggle thinking display (currently ${DEFAULT_SHOW_REASONING ? "on" : "off"})`,
+      `- \`/reasoning\` — Toggle thinking display _(currently ${DEFAULT_SHOW_REASONING ? "on" : "off"})_`,
     );
     expect(text).toContain(
-      "/verbose  Toggle verbose tool rendering (currently off)",
+      "- `/verbose` — Toggle verbose tool rendering _(currently off)_",
     );
-    expect(text).toContain("/todo  Show the current todo list");
+    expect(text).toContain("- `/todo` — Show the current todo list");
   });
 
-  test("buildHelpText describes the current Escape behavior", () => {
+  test("buildHelpText lists the supported keyboard shortcuts in markdown", () => {
     const helpState: HelpRenderState = {
       providers: new Map(),
       model: null,
@@ -38,13 +40,26 @@ describe("ui/help", () => {
 
     const text = buildHelpText(helpState);
 
+    expect(text).toContain("## Keyboard");
+    expect(text).toContain("- `Enter` submits the current draft.");
+    expect(text).toContain("- `Shift+Enter` inserts a newline.");
     expect(text).toContain(
-      "Escape closes the current overlay and returns focus to the input",
+      "- `Tab` opens command autocomplete when the draft starts with `/`.",
     );
     expect(text).toContain(
-      "With no overlay open, Escape interrupts the current turn",
+      "- Otherwise, `Tab` autocompletes file paths and can open a path picker when there are multiple matches.",
     );
-    expect(text).toContain("Otherwise Escape does nothing");
+    expect(text).toContain("- `Ctrl+R` opens global input history search.");
+    expect(text).toContain(
+      "- `Escape` closes the current overlay and returns focus to the input.",
+    );
+    expect(text).toContain(
+      "- With no overlay open, `Escape` interrupts the current turn.",
+    );
+    expect(text).toContain("- Otherwise, `Escape` does nothing.");
+    expect(text).toContain("- `Ctrl+C` exits gracefully.");
+    expect(text).toContain("- `Ctrl+D` exits when the input is empty.");
+    expect(text).toContain("- `Ctrl+Z` suspends the app to the background.");
     expect(text).not.toContain("Escape blurs the input first");
   });
 });

package/src/ui/help.ts

@@ -47,7 +47,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, string> = {
  *
  * @param command - Command name.
  * @param state - Help-relevant application state.
- * @returns Human-readable command description.
+ * @returns Markdown-ready command description.
  */
 function getHelpCommandDescription(
   command: (typeof COMMANDS)[number],
@@ -55,72 +55,86 @@ function getHelpCommandDescription(
 ): string {
   const description = COMMAND_DESCRIPTIONS[command] ?? "";
   if (command === "reasoning") {
-    return `${description} (currently ${state.showReasoning ? "on" : "off"})`;
+    return `${description} _(currently ${state.showReasoning ? "on" : "off"})_`;
   }
   if (command === "verbose") {
-    return `${description} (currently ${state.verbose ? "on" : "off"})`;
+    return `${description} _(currently ${state.verbose ? "on" : "off"})_`;
   }
   return description;
 }
 
+function formatInlineCode(text: string): string {
+  return `\`${text}\``;
+}
+
+function formatInlineCodeList(items: readonly string[]): string {
+  return items.map((item) => formatInlineCode(item)).join(", ");
+}
+
 /**
  * Build the `/help` text shown in the conversation log.
  *
  * @param state - Help-relevant application state.
- * @returns Multi-line help text for display.
+ * @returns Multi-line markdown help text for display.
  */
 export function buildHelpText(state: HelpRenderState): string {
-  const lines: string[] = [];
+  const lines: string[] = ["# Help", "", "## Commands", ""];
 
-  lines.push("Commands:");
   for (const command of COMMANDS) {
-    lines.push(`  /${command}  ${getHelpCommandDescription(command, state)}`);
+    lines.push(
+      `- ${formatInlineCode(`/${command}`)} — ${getHelpCommandDescription(command, state)}`,
+    );
   }
 
   const providerNames = Array.from(state.providers.keys());
-  lines.push("");
-  lines.push("Note:");
-  lines.push(
-    "  Escape closes the current overlay and returns focus to the input.",
-  );
-  lines.push("  With no overlay open, Escape interrupts the current turn.");
-  lines.push("  Otherwise Escape does nothing.");
-
-  lines.push("");
   lines.push(
+    "",
+    "## Keyboard",
+    "",
+    "- `Enter` submits the current draft.",
+    "- `Shift+Enter` inserts a newline.",
+    "- `Tab` opens command autocomplete when the draft starts with `/`.",
+    "- Otherwise, `Tab` autocompletes file paths and can open a path picker when there are multiple matches.",
+    "- `Ctrl+R` opens global input history search.",
+    "- `Escape` closes the current overlay and returns focus to the input.",
+    "- With no overlay open, `Escape` interrupts the current turn.",
+    "- Otherwise, `Escape` does nothing.",
+    "- `Ctrl+C` exits gracefully.",
+    "- `Ctrl+D` exits when the input is empty.",
+    "- `Ctrl+Z` suspends the app to the background.",
+    "",
+    "## Current state",
+    "",
     providerNames.length > 0
-      ? `Providers: ${providerNames.join(", ")}`
-      : "Providers: none (use /login)",
-  );
-
-  lines.push(
+      ? `- Providers: ${formatInlineCodeList(providerNames)}`
+      : "- Providers: none — use `/login`",
     state.model
-      ? `Model: ${state.model.provider}/${state.model.id}`
-      : "Model: none (use /model)",
+      ? `- Model: ${formatInlineCode(`${state.model.provider}/${state.model.id}`)}`
+      : "- Model: none — use `/model`",
   );
 
   if (state.agentsMd.length > 0) {
-    lines.push("");
-    lines.push("AGENTS.md files:");
+    lines.push("", "## Loaded `AGENTS.md` files", "");
     for (const agentFile of state.agentsMd) {
-      lines.push(`  ${abbreviatePath(agentFile.path)}`);
+      lines.push(`- ${formatInlineCode(abbreviatePath(agentFile.path))}`);
     }
   }
 
   if (state.skills.length > 0) {
-    lines.push("");
-    lines.push("Skills:");
+    lines.push("", "## Skills", "");
     for (const skill of state.skills) {
-      const description = skill.description ? `  ${skill.description}` : "";
-      lines.push(`  ${skill.name}${description}`);
+      lines.push(
+        skill.description
+          ? `- ${formatInlineCode(skill.name)} — ${skill.description}`
+          : `- ${formatInlineCode(skill.name)}`,
+      );
     }
   }
 
   if (state.plugins.length > 0) {
-    lines.push("");
-    lines.push("Plugins:");
+    lines.push("", "## Plugins", "");
     for (const plugin of state.plugins) {
-      lines.push(`  ${plugin.entry.name}`);
+      lines.push(`- ${formatInlineCode(plugin.entry.name)}`);
     }
   }
 

package/src/ui.ts

@@ -26,6 +26,7 @@ import {
   appendMessage,
   createUiMessage,
   createUiTodoMessage,
+  type UiInfoFormat,
 } from "./session.ts";
 import type { Theme } from "./theme.ts";
 import {
@@ -64,6 +65,23 @@ const DIVIDER_FRAME_MS = 60;
 /** Width of the bright pulse segment in the animated divider. */
 const PULSE_WIDTH = 5;
 
+/** Number of trailing words shown in the idle terminal-title preview. */
+const TERMINAL_TITLE_WORD_COUNT = 5;
+
+/** Divider ticks spent on each animated terminal-title scanner frame. */
+const TERMINAL_TITLE_TICKS_PER_FRAME = 4;
+
+/** Frames used for the active terminal-title glow-scanner animation. */
+const TERMINAL_TITLE_FRAMES = [
+  "[=o---]",
+  "[-=o--]",
+  "[--=o-]",
+  "[---=o]",
+  "[--o=-]",
+  "[-o=--]",
+  "[o=---]",
+] as const;
+
 /** Maximum number of committed messages rendered before older history is chunked. */
 const CONVERSATION_CHUNK_MESSAGES = 50;
 
@@ -109,6 +127,15 @@ let dividerTimer: ReturnType<typeof setInterval> | null = null;
 /** Whether stdin was already in raw mode before the TUI initialized. */
 let stdinWasRaw = false;
 
+/** Latest application state associated with the active terminal UI. */
+let titleState: AppState | null = null;
+
+/** Whether a cel viewport has rendered for the current UI session. */
+let titleViewportActive = false;
+
+/** Last terminal title written during the current UI session. */
+let lastTerminalTitle: string | null = null;
+
 // ---------------------------------------------------------------------------
 // Overlay state
 // ---------------------------------------------------------------------------
@@ -150,6 +177,148 @@ export function resetUiState(): void {
   resetConversationRenderCache();
   activeOverlay = null;
   stdinWasRaw = false;
+  titleState = null;
+  titleViewportActive = false;
+  lastTerminalTitle = null;
+}
+
+// ---------------------------------------------------------------------------
+// Terminal title
+// ---------------------------------------------------------------------------
+
+function collapseTerminalTitleText(text: string): string | null {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  return collapsed.length > 0 ? collapsed : null;
+}
+
+function getUserTerminalTitleText(
+  content: Extract<AppState["messages"][number], { role: "user" }>["content"],
+): string | null {
+  if (typeof content === "string") {
+    return collapseTerminalTitleText(content);
+  }
+
+  const text = content
+    .filter(
+      (block): block is Extract<(typeof content)[number], { type: "text" }> => {
+        return block.type === "text";
+      },
+    )
+    .map((block) => block.text)
+    .join(" ");
+
+  return collapseTerminalTitleText(text);
+}
+
+function getAssistantTerminalTitleText(
+  content: Extract<
+    AppState["messages"][number],
+    { role: "assistant" }
+  >["content"],
+): string | null {
+  const text = content
+    .filter(
+      (
+        block,
+      ): block is Extract<
+        Extract<
+          AppState["messages"][number],
+          { role: "assistant" }
+        >["content"][number],
+        { type: "text" }
+      > => {
+        return block.type === "text";
+      },
+    )
+    .map((block) => block.text)
+    .join(" ");
+
+  return collapseTerminalTitleText(text);
+}
+
+function truncateTerminalTitleTail(text: string): string {
+  const words = text.split(" ");
+  if (words.length <= TERMINAL_TITLE_WORD_COUNT) {
+    return text;
+  }
+  return `...${words.slice(-TERMINAL_TITLE_WORD_COUNT).join(" ")}`;
+}
+
+function buildIdleTerminalTitle(state: Pick<AppState, "messages">): string {
+  for (let index = state.messages.length - 1; index >= 0; index -= 1) {
+    const message = state.messages[index];
+    if (!message) {
+      continue;
+    }
+
+    let text: string | null = null;
+    switch (message.role) {
+      case "user":
+        text = getUserTerminalTitleText(message.content);
+        break;
+      case "assistant":
+        text = getAssistantTerminalTitleText(message.content);
+        break;
+      case "toolResult":
+      case "ui":
+        break;
+    }
+
+    if (text) {
+      return `mc - ${truncateTerminalTitleTail(text)}`;
+    }
+  }
+
+  return "mc";
+}
+
+/**
+ * Build the current terminal title from UI state.
+ *
+ * Idle titles show a short tail preview from the latest conversational text
+ * message. Active turns show a stable-width glow scanner.
+ *
+ * @param state - Application state needed to derive the title.
+ * @param animationTick - Divider animation tick used to pick the scanner frame.
+ * @returns The terminal title text to write via cel-tui.
+ */
+export function buildTerminalTitle(
+  state: Pick<AppState, "messages" | "running">,
+  animationTick = dividerTick,
+): string {
+  if (!state.running) {
+    return buildIdleTerminalTitle(state);
+  }
+
+  const frameIndex =
+    Math.floor(animationTick / TERMINAL_TITLE_TICKS_PER_FRAME) %
+    TERMINAL_TITLE_FRAMES.length;
+  return `mc - ${TERMINAL_TITLE_FRAMES[frameIndex]}`;
+}
+
+function syncTerminalTitle(
+  state: Pick<AppState, "messages" | "running"> | null,
+): void {
+  if (!state || !titleViewportActive) {
+    return;
+  }
+
+  const title = buildTerminalTitle(state);
+  if (title === lastTerminalTitle) {
+    return;
+  }
+
+  cel.setTitle(title);
+  lastTerminalTitle = title;
+}
+
+function invalidateTerminalTitleCache(): void {
+  lastTerminalTitle = null;
+}
+
+function requestRender(): void {
+  syncTerminalTitle(titleState);
+  cel.render();
 }
 
 // ---------------------------------------------------------------------------
@@ -162,7 +331,7 @@ function startDividerAnimation(): void {
   dividerTick = 0;
   dividerTimer = setInterval(() => {
     dividerTick++;
-    cel.render();
+    requestRender();
   }, DIVIDER_FRAME_MS);
 }
 
@@ -286,14 +455,14 @@ function prependConversationChunk(state: AppState, width: number): void {
 function openOverlay(overlay: ActiveOverlay): void {
   activeOverlay = overlay;
   inputFocused = false;
-  cel.render();
+  requestRender();
 }
 
 /** Dismiss the active overlay and return focus to the input. */
 function dismissOverlay(): void {
   activeOverlay = null;
   inputFocused = true;
-  cel.render();
+  requestRender();
 }
 
 function openPathAutocompleteOverlay(state: AppState): void {
@@ -331,7 +500,7 @@ function handleTabKeyPress(state: AppState): void {
   const completedInput = autocompleteInputPath(inputValue, state.cwd);
   if (completedInput) {
     inputValue = completedInput;
-    cel.render();
+    requestRender();
     return;
   }
 
@@ -366,18 +535,20 @@ export function renderActiveOverlay(state: AppState): Node | null {
  * @returns Stable callbacks for the controlled TextInput.
  */
 export function createInputController(state: AppState): InputController {
+  titleState = state;
+
   return {
     onChange: (value) => {
       inputValue = value;
-      cel.render();
+      requestRender();
     },
     onFocus: () => {
       inputFocused = true;
-      cel.render();
+      requestRender();
     },
     onBlur: () => {
       inputFocused = false;
-      cel.render();
+      requestRender();
     },
     onKeyPress: (key) => {
       if (key === "enter") {
@@ -385,13 +556,13 @@ export function createInputController(state: AppState): InputController {
 
         if (isQuitInput(raw)) {
           inputValue = "";
-          cel.render();
+          requestRender();
           requestGracefulExit(state);
           return false;
         }
 
         inputValue = "";
-        cel.render();
+        requestRender();
         handleInput(raw, state);
         return false;
       }
@@ -479,7 +650,7 @@ function appendUiMessage(
   }
   state.messages.push(message);
   scrollConversationToBottom();
-  cel.render();
+  requestRender();
 }
 
 /**
@@ -490,9 +661,14 @@ function appendUiMessage(
  *
  * @param text - Display text to append.
  * @param state - Application state.
+ * @param format - Optional rich-text format hint for the content.
  */
-function appendInfoMessage(text: string, state: AppState): void {
-  appendUiMessage(createUiMessage(text), state);
+function appendInfoMessage(
+  text: string,
+  state: AppState,
+  format?: UiInfoFormat,
+): void {
+  appendUiMessage(createUiMessage(text, format), state);
 }
 
 /**
@@ -521,9 +697,7 @@ const commandController = createCommandController({
   appendInfoMessage,
   appendTodoMessage,
   scrollConversationToBottom,
-  render: () => {
-    cel.render();
-  },
+  render: requestRender,
   reloadPromptContext,
   openInBrowser,
 });
@@ -537,9 +711,7 @@ const agentController = createUiAgentController({
   appendInfoMessage,
   handleCommand: (command, state) =>
     commandController.handleCommand(command, state),
-  render: () => {
-    cel.render();
-  },
+  render: requestRender,
   scrollConversationToBottom,
   startDividerAnimation,
   stopDividerAnimation,
@@ -547,6 +719,7 @@ const agentController = createUiAgentController({
 
 /** Route raw user input through parseInput and dispatch accordingly. */
 export function handleInput(raw: string, state: AppState): void {
+  titleState = state;
   agentController.handleInput(raw, state);
 }
 
@@ -618,6 +791,7 @@ export function suspendToBackground(
   stop();
   onResume(() => {
     clearInterval(keepAlive);
+    invalidateTerminalTitleCache();
     resumeUi();
   });
 
@@ -657,7 +831,7 @@ function renderConversationLog(state: AppState, width: number): Node {
           prependConversationChunk(state, width);
         }
 
-        cel.render();
+        requestRender();
       },
     },
     buildConversationLog(state, width),
@@ -681,6 +855,12 @@ export function renderBaseLayout(
   inputController: InputController,
   onSuspend?: () => void,
 ): Node {
+  titleState = state;
+  titleViewportActive = true;
+  if (lastTerminalTitle === null) {
+    syncTerminalTitle(state);
+  }
+
   return VStack(
     {
       height: "100%",
@@ -736,6 +916,7 @@ export function renderBaseLayout(
 export function startUI(state: AppState): void {
   resetUiState();
   stdinWasRaw = process.stdin.isRaw || false;
+  titleState = state;
   const terminal = new ProcessTerminal();
   const inputController = createInputController(state);
   cel.init(terminal);
@@ -749,7 +930,7 @@ export function startUI(state: AppState): void {
         if (state.running) {
           startDividerAnimation();
         }
-        cel.render();
+        requestRender();
       });
     });
     const overlay = renderActiveOverlay(state);
@@ -759,6 +940,7 @@ export function startUI(state: AppState): void {
     }
     return base;
   });
+  syncTerminalTitle(state);
 
   if (state.running) {
     startDividerAnimation();