fix(cli): keep framed TUI wraps in gutter

- Wrap framed card body text before Ink can soft-wrap it

- Cover error, info, final output, and zero-column PTY cases

Co-Authored-By: devagent <devagent@egavrin>

Author: egavrin

packages/cli/src/tui/App.test.ts

@@ -16,6 +16,7 @@ import { StatusBar } from "./StatusBar.js";
 import { useAgentLog } from "./useAgentLog.js";
 import type { PresentedTurnStatus } from "../transcript-composer.js";
 import {
+  makeErrorPart,
   makeFinalOutputPart,
   makeInfoPart,
   makeTurnSummaryPart,
@@ -81,6 +82,21 @@ function countPromptPlaceholders(text: string): number {
   return (stripAnsi(text).match(/Ask anything…/g) ?? []).length;
 }
 
+function outputLines(text: string): string[] {
+  return stripAnsi(text).replace(/\r/g, "\n").split("\n");
+}
+
+function expectWrappedCardFragmentsInsideGutter(text: string, fragments: ReadonlyArray<string>): void {
+  const lines = outputLines(text);
+  for (const fragment of fragments) {
+    const matchingLines = lines.filter((line) => line.includes(fragment));
+    expect(matchingLines, `expected output to include fragment ${fragment}`).not.toEqual([]);
+    for (const line of matchingLines) {
+      expect(line, `fragment ${fragment} should stay inside the card gutter`).toMatch(/^  │ /);
+    }
+  }
+}
+
 async function typeAndSubmit(stdin: TestInput, text: string): Promise<void> {
   stdin.write(text);
   await settle();
@@ -738,6 +754,72 @@ describe("interactive completion notices", () => {
   });
 });
 
+describe("framed TUI wrapping", () => {
+  const cases: Array<{
+    readonly name: string;
+    readonly columns: number;
+    readonly node: TranscriptNode;
+    readonly fragments: ReadonlyArray<string>;
+  }> = [
+    {
+      name: "error card",
+      columns: 72,
+      node: makeTurnNode(
+        "Verify image",
+        [{
+          id: "provider-error-1",
+          part: makeErrorPart({
+            message: "Provider error (attempt 1, ProviderError): OpenAI API error: terminated. Retrying in 611ms...",
+            code: "PROVIDER_RETRY",
+          }),
+        }],
+        { status: "error", elapsedMs: 300 },
+      ),
+      fragments: ["Provider error", "Retrying in", "611ms"],
+    },
+    {
+      name: "info card",
+      columns: 66,
+      node: {
+        id: "info-1",
+        kind: "part",
+        part: makeInfoPart("status", [
+          "A very long status update is rendered as a transcript card and should wrap through the shared framed-line gutter instead of escaping to column zero.",
+        ]),
+      },
+      fragments: ["A very long", "shared framed-line", "column zero"],
+    },
+    {
+      name: "final output card",
+      columns: 68,
+      node: makeTurnNode(
+        "Explain retry",
+        [{
+          id: "final-wrap-1",
+          part: makeFinalOutputPart("**Provider retry** details stay visible while markdown formatted assistant output wraps inside the framed response gutter."),
+        }],
+        { status: "completed", elapsedMs: 300 },
+      ),
+      fragments: ["Provider retry", "markdown formatted", "response gutter"],
+    },
+  ];
+
+  it.each(cases)("keeps wrapped $name text inside the left gutter", async ({ columns, fragments, node }) => {
+    const view = renderForTest(
+      React.createElement(TranscriptView, {
+        showWelcome: false,
+        model: "test-model",
+        transcriptNodes: [node],
+      }),
+      { columns },
+    );
+
+    await settle();
+
+    expectWrappedCardFragmentsInsideGutter(view.stdout.readAll(), fragments);
+  });
+});
+
 describe("interactive transcript typed rows", () => {
   it("renders typed progress and status transcript rows for compaction and approvals", async () => {
     const view = renderForTest(React.createElement(StatusHarness));

packages/cli/src/tui/FinalOutput.tsx

@@ -2,18 +2,21 @@
  * FinalOutput — renders the agent's final response inside the transcript card system.
  */
 
-import { Box, Text } from "ink";
+import { Box, Text, useStdout } from "ink";
 import React from "react";
 
+import { framedBodyWidth, wrapAnsiTextByWidth } from "./shared.js";
 import { renderMarkdown } from "../markdown-render.js";
 
 interface FinalOutputProps {
   readonly text: string;
 }
 
 export function FinalOutput({ text }: FinalOutputProps): React.ReactElement {
+  const { stdout } = useStdout();
   const rendered = renderMarkdown(text);
-  const lines = rendered.split("\n");
+  const bodyWidth = framedBodyWidth(stdout.columns);
+  const lines = rendered.split("\n").flatMap((line) => wrapAnsiTextByWidth(line, bodyWidth));
 
   return (
     <Box flexDirection="column" marginTop={1}>

packages/cli/src/tui/LogEntryView.tsx

@@ -4,7 +4,7 @@
  * Used by both App.tsx and SingleShotApp.tsx.
  */
 
-import { Box, Text } from "ink";
+import { Box, Text, useStdout } from "ink";
 import React from "react";
 
 import { FinalOutput } from "./FinalOutput.js";
@@ -20,7 +20,7 @@ import {
   ValidationResultDisplay,
 } from "./ToolDisplay.js";
 import type { PresentedStatus } from "../transcript-presenter.js";
-import { cleanTime } from "./shared.js";
+import { cleanTime, framedBodyWidth, wrapAnsiTextByWidth } from "./shared.js";
 export const LogEntryView = React.memo(function LogEntryView({ entry }: { entry: LogEntry }): React.ReactElement | null {
   const direct = renderDirectEntry(entry);
   if (direct !== undefined) return direct;
@@ -146,18 +146,23 @@ function TranscriptCard(
     readonly marginTop?: number;
   },
 ): React.ReactElement {
+  const { stdout } = useStdout();
+  const bodyWidth = framedBodyWidth(stdout.columns);
+
   return (
     <Box flexDirection="column" marginTop={marginTop}>
       <Text>
         <Text dimColor>  ╭─ </Text>
         <Text color={color}>{title}</Text>
       </Text>
-      {lines.map((line, index) => (
-        <Text key={`${title}-${index}`}>
-          <Text dimColor>  │ </Text>
-          <Text bold={boldBody}>{line}</Text>
-        </Text>
-      ))}
+      {lines
+        .flatMap((line) => wrapAnsiTextByWidth(line, bodyWidth))
+        .map((line, index) => (
+          <Text key={`${title}-${index}`}>
+            <Text dimColor>  │ </Text>
+            <Text bold={boldBody}>{line}</Text>
+          </Text>
+        ))}
       <Text dimColor>  ╰─</Text>
     </Box>
   );

packages/cli/src/tui/MessageView.tsx

@@ -1,18 +1,25 @@
-import { Box, Text } from "ink";
+import { Box, Text, useStdout } from "ink";
 import React from "react";
 
+import { framedBodyWidth, wrapAnsiTextByWidth } from "./shared.js";
+
 export function ErrorView({ message, code }: { message: string; code: string }): React.ReactElement {
+  const { stdout } = useStdout();
+  const body = code && code !== "LSP_INFO" ? `${message} (${code})` : message;
+  const rows = wrapAnsiTextByWidth(body, framedBodyWidth(stdout.columns));
+
   return (
     <Box flexDirection="column">
       <Text>
         <Text dimColor>  ╭─ </Text>
         <Text color="red">error</Text>
       </Text>
-      <Text>
-        <Text dimColor>  │ </Text>
-        <Text color="red">{message}</Text>
-        {code && code !== "LSP_INFO" && <Text dimColor> ({code})</Text>}
-      </Text>
+      {rows.map((row, index) => (
+        <Text key={`error-line-${index}`}>
+          <Text dimColor>  │ </Text>
+          <Text color="red">{row}</Text>
+        </Text>
+      ))}
       <Text dimColor>  ╰─</Text>
     </Box>
   );

packages/cli/src/tui/PromptInput.test.ts

@@ -13,7 +13,7 @@ import {
   shouldSubmitPromptInput,
   SLASH_COMMANDS,
 } from "./PromptInput.js";
-import { cycleApprovalMode, resolvePromptTabAction } from "./shared.js";
+import { cycleApprovalMode, framedBodyWidth, resolvePromptTabAction, resolveTerminalColumns } from "./shared.js";
 
 describe("PromptInput slash completions", () => {
   it("includes review and simplify prompt shortcuts", () => {
@@ -114,6 +114,21 @@ describe("PromptInput layout helpers", () => {
     ]);
     expect(rows.map((row) => stringWidth(row.text))).toEqual([4, 1]);
   });
+
+  it("falls back when a PTY reports zero terminal columns", () => {
+    const previousColumns = process.env["COLUMNS"];
+    process.env["COLUMNS"] = "120";
+    try {
+      expect(resolveTerminalColumns(0)).toBe(120);
+      expect(framedBodyWidth(0)).toBe(116);
+    } finally {
+      if (previousColumns === undefined) {
+        delete process.env["COLUMNS"];
+      } else {
+        process.env["COLUMNS"] = previousColumns;
+      }
+    }
+  });
 });
 
 describe("safety mode helpers", () => {

packages/cli/src/tui/PromptInput.tsx

@@ -21,7 +21,7 @@ import { join, dirname, basename } from "node:path";
 import React, { useRef, useState } from "react";
 import stringWidth from "string-width";
 
-import { getApprovalModeColor, resolvePromptTabAction } from "./shared.js";
+import { getApprovalModeColor, resolvePromptTabAction, resolveTerminalColumns } from "./shared.js";
 
 export const SLASH_COMMANDS = [
   "/help",
@@ -395,7 +395,7 @@ export function PromptInput({
   const savedInputRef = useRef("");
   const { stdout } = useStdout();
   const accentColor = getApprovalModeColor(approvalMode);
-  const contentWidth = Math.max(1, (stdout.columns ?? 80) - INPUT_FRAME_WIDTH);
+  const contentWidth = Math.max(1, resolveTerminalColumns(stdout.columns) - INPUT_FRAME_WIDTH);
   const promptRows = buildPromptRows(value, cursorPos, placeholder, contentWidth);
   useInput((input, key) => {
     handlePromptInput(input, key, {

packages/cli/src/tui/shared.ts

@@ -3,6 +3,7 @@
  */
 
 import { SafetyMode } from "@devagent/runtime";
+import stringWidth from "string-width";
 
 import type { TranscriptNode } from "../transcript-composer.js";
 import type { TranscriptPart } from "../transcript-presenter.js";
@@ -38,6 +39,11 @@ const APPROVAL_MODE_ORDER = [
 ] as const;
 
 type PromptTabAction = "cycle-mode" | "complete" | "none";
+const FRAMED_BODY_PREFIX = "  │ ";
+const DEFAULT_TERMINAL_COLUMNS = 80;
+const GRAPHEME_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+const ANSI_CSI_PATTERN = /^\x1B\[[0-?]*[ -/]*[@-~]/;
+const ANSI_OSC_PATTERN = /^\x1B\][\s\S]*?(?:\x07|\x1B\\)/;
 
 export function cycleApprovalMode(mode: string): SafetyMode {
   const currentIndex = APPROVAL_MODE_ORDER.indexOf(mode as SafetyMode);
@@ -67,6 +73,61 @@ export function cleanTime(text: string): string {
   return text.replace(/(\d+)\.\d+s/g, "$1s");
 }
 
+export function resolveTerminalColumns(columns: number | undefined): number {
+  if (columns !== undefined && columns > 0) {
+    return columns;
+  }
+  const envColumns = Number.parseInt(process.env["COLUMNS"] ?? "", 10);
+  return Number.isFinite(envColumns) && envColumns > 0 ? envColumns : DEFAULT_TERMINAL_COLUMNS;
+}
+
+export function framedBodyWidth(columns: number | undefined): number {
+  return Math.max(1, resolveTerminalColumns(columns) - FRAMED_BODY_PREFIX.length);
+}
+
+export function wrapAnsiTextByWidth(text: string, width: number): string[] {
+  const maxWidth = Math.max(1, width);
+  if (text.length === 0) return [""];
+
+  const rows: string[] = [];
+  let current = "";
+  let currentWidth = 0;
+  let index = 0;
+
+  while (index < text.length) {
+    const remaining = text.slice(index);
+    const controlSequence = readAnsiSequence(remaining);
+    if (controlSequence) {
+      current += controlSequence;
+      index += controlSequence.length;
+      continue;
+    }
+
+    const grapheme = nextGrapheme(remaining);
+    const graphemeWidth = stringWidth(grapheme);
+    if (currentWidth > 0 && currentWidth + graphemeWidth > maxWidth) {
+      rows.push(current);
+      current = "";
+      currentWidth = 0;
+    }
+
+    current += grapheme;
+    currentWidth += graphemeWidth;
+    index += grapheme.length;
+  }
+
+  rows.push(current);
+  return rows;
+}
+
+function readAnsiSequence(text: string): string | null {
+  return text.match(ANSI_CSI_PATTERN)?.[0] ?? text.match(ANSI_OSC_PATTERN)?.[0] ?? null;
+}
+
+function nextGrapheme(text: string): string {
+  return GRAPHEME_SEGMENTER.segment(text)[Symbol.iterator]().next().value?.segment ?? text[0] ?? "";
+}
+
 export function tokenProgressBar(used: number, max: number): string {
   const pct = Math.round((used / max) * 100);
   const width = 20;