From adede04415f7e17b51200eadc3cede9b3e052ef0 Mon Sep 17 00:00:00 2001
From: Hao Yan <haoyan160@gmail.com>
Date: Fri, 10 Jul 2026 15:16:18 -0600
Subject: [PATCH 1/5] feat(render): add width-aware text wrapping with minimal
 markdown styling

---
 src/render/wrap.ts        | 158 ++++++++++++++++++++++++++++++++++++++
 tests/render/wrap.test.ts |  88 +++++++++++++++++++++
 2 files changed, 246 insertions(+)
 create mode 100644 src/render/wrap.ts
 create mode 100644 tests/render/wrap.test.ts

diff --git a/src/render/wrap.ts b/src/render/wrap.ts
new file mode 100644
index 0000000..0880d95
--- /dev/null
+++ b/src/render/wrap.ts
@@ -0,0 +1,158 @@
+/**
+ * Width-aware text wrapping with minimal markdown treatment, for rendering
+ * free-form text (e.g. an RCA result) that may contain light markdown from an
+ * LLM. Pure string transform — no I/O, no width detection — so callers pass in
+ * an explicit width (typically `process.stdout.columns ?? 80`) and a `bold`
+ * styler (typically `createStyler(sink).bold`), keeping this testable without a
+ * real TTY.
+ *
+ * Handled, deliberately minimally:
+ *  - `# `..`###### ` headings: the `#` marker is stripped and the heading text
+ *    is styled bold (or left plain when `bold` is a no-op).
+ *  - `**bold**` spans: the `**` markers are stripped and the enclosed text is
+ *    styled bold.
+ *  - `` `code` `` spans: the backticks are stripped (left plain).
+ *  - `-`/`*`/`1.`-style list items: wrapped with a hanging indent so
+ *    continuation lines align under the item's text rather than the marker.
+ *  - Plain paragraphs (consecutive non-blank, non-list, non-heading lines):
+ *    joined and re-wrapped to `width`; blank lines are preserved as paragraph
+ *    separators.
+ *
+ * Never emits a literal `#`/`**`/backtick marker for the constructs above.
+ */
+
+/** A styling function, e.g. `Styler["bold"]`; identity for plain-text output. */
+export type StyleFn = (text: string) => string;
+
+const HEADING_RE = /^(#{1,6})\s+(.*)$/;
+const LIST_ITEM_RE = /^(\s*)([-*]|\d+\.)\s+(.*)$/;
+const BOLD_SPAN_RE = /\*\*(.+?)\*\*/g;
+const CODE_SPAN_RE = /`([^`]+)`/g;
+
+interface Word {
+  plain: string;
+  bold: boolean;
+}
+
+/** Strips inline code backticks (left plain) then splits `**bold**` spans out. */
+function tokenizeInline(text: string): Array<{ text: string; bold: boolean }> {
+  const noCode = text.replace(CODE_SPAN_RE, "$1");
+  const tokens: Array<{ text: string; bold: boolean }> = [];
+  let last = 0;
+  for (const match of noCode.matchAll(BOLD_SPAN_RE)) {
+    const index = match.index ?? 0;
+    if (index > last) {
+      tokens.push({ text: noCode.slice(last, index), bold: false });
+    }
+    tokens.push({ text: match[1] ?? "", bold: true });
+    last = index + match[0].length;
+  }
+  if (last < noCode.length) {
+    tokens.push({ text: noCode.slice(last), bold: false });
+  }
+  return tokens;
+}
+
+/** Splits inline-tokenized text into individual words, each carrying its emphasis. */
+function toWords(text: string): Word[] {
+  const words: Word[] = [];
+  for (const token of tokenizeInline(text)) {
+    for (const plain of token.text.split(/\s+/)) {
+      if (plain.length > 0) {
+        words.push({ plain, bold: token.bold });
+      }
+    }
+  }
+  return words;
+}
+
+/**
+ * Greedily fills lines up to `width` visible columns (ANSI escapes added by
+ * `style` don't count toward width, since wrapping decisions use `plain`
+ * lengths). `firstPrefix` prefixes the first output line (e.g. a list marker);
+ * `contPrefix` prefixes every following line (e.g. matching spaces), so
+ * continuation lines align under the first line's text.
+ */
+function fillLines(
+  words: Word[],
+  width: number,
+  style: StyleFn,
+  firstPrefix: string,
+  contPrefix: string,
+): string[] {
+  const safeWidth = Math.max(1, width);
+  const lines: string[] = [];
+  let current: Word[] = [];
+  let currentLen = firstPrefix.length;
+
+  const flush = (): void => {
+    const prefix = lines.length === 0 ? firstPrefix : contPrefix;
+    lines.push(prefix + current.map((w) => (w.bold ? style(w.plain) : w.plain)).join(" "));
+    current = [];
+    currentLen = contPrefix.length;
+  };
+
+  for (const word of words) {
+    const sep = current.length === 0 ? 0 : 1;
+    if (current.length > 0 && currentLen + sep + word.plain.length > safeWidth) {
+      flush();
+    }
+    current.push(word);
+    currentLen += (current.length === 1 ? 0 : 1) + word.plain.length;
+  }
+  if (current.length > 0 || lines.length === 0) {
+    flush();
+  }
+  return lines;
+}
+
+/**
+ * Wraps `text` to `width` columns, applying minimal markdown styling (see
+ * module doc). `bold` is applied to headings and `**bold**` spans; pass the
+ * identity function for a plain-text (no-ANSI) fallback.
+ */
+export function wrapMarkdown(text: string, width: number, bold: StyleFn = (s) => s): string {
+  const out: string[] = [];
+  let paragraph: string[] = [];
+
+  const flushParagraph = (): void => {
+    if (paragraph.length === 0) {
+      return;
+    }
+    const joined = paragraph.join(" ").trim();
+    out.push(...fillLines(toWords(joined), width, bold, "", ""));
+    paragraph = [];
+  };
+
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trimEnd();
+    if (line.trim() === "") {
+      flushParagraph();
+      out.push("");
+      continue;
+    }
+
+    const heading = HEADING_RE.exec(line);
+    if (heading) {
+      flushParagraph();
+      const words = toWords((heading[2] ?? "").trim()).map((w) => ({ ...w, bold: true }));
+      out.push(...fillLines(words, width, bold, "", ""));
+      continue;
+    }
+
+    const listItem = LIST_ITEM_RE.exec(line);
+    if (listItem) {
+      flushParagraph();
+      const [, indent, marker, rest] = listItem;
+      const firstPrefix = `${indent ?? ""}${marker ?? ""} `;
+      const contPrefix = " ".repeat(firstPrefix.length);
+      out.push(...fillLines(toWords(rest ?? ""), width, bold, firstPrefix, contPrefix));
+      continue;
+    }
+
+    paragraph.push(line.trim());
+  }
+  flushParagraph();
+
+  return out.join("\n");
+}
diff --git a/tests/render/wrap.test.ts b/tests/render/wrap.test.ts
new file mode 100644
index 0000000..5380236
--- /dev/null
+++ b/tests/render/wrap.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { wrapMarkdown } from "../../src/render/wrap.js";
+
+const bold = (text: string): string => `**${text}**`; // fake styler distinct from markdown `**`
+
+describe("wrapMarkdown", () => {
+  it("wraps a long paragraph so no line exceeds the given width", () => {
+    const text = Array.from({ length: 30 }, (_, i) => `word${i}`).join(" ");
+    const wrapped = wrapMarkdown(text, 20);
+    for (const line of wrapped.split("\n")) {
+      expect(line.length).toBeLessThanOrEqual(20);
+    }
+    // no words dropped
+    for (let i = 0; i < 30; i++) {
+      expect(wrapped).toContain(`word${i}`);
+    }
+  });
+
+  it("joins single newlines within a paragraph before rewrapping", () => {
+    const text = "one two three\nfour five six";
+    const wrapped = wrapMarkdown(text, 80);
+    expect(wrapped).toBe("one two three four five six");
+  });
+
+  it("preserves blank lines as paragraph separators", () => {
+    const text = "first paragraph\n\nsecond paragraph";
+    const wrapped = wrapMarkdown(text, 80);
+    expect(wrapped).toBe("first paragraph\n\nsecond paragraph");
+  });
+
+  it("strips a leading heading marker and never prints it literally", () => {
+    const wrapped = wrapMarkdown("## Root Cause", 80, (s) => `[B]${s}[/B]`);
+    expect(wrapped).not.toContain("##");
+    // Styled per word (visually equivalent bolding), not merged into one span.
+    expect(wrapped).toBe("[B]Root[/B] [B]Cause[/B]");
+  });
+
+  it("leaves a heading as plain text when no styler is given", () => {
+    const wrapped = wrapMarkdown("# Title", 80);
+    expect(wrapped).toBe("Title");
+  });
+
+  it("strips ** markers and styles the enclosed text as bold", () => {
+    const wrapped = wrapMarkdown("this is **important** text", 80, (s) => `[B]${s}[/B]`);
+    expect(wrapped).not.toContain("**");
+    expect(wrapped).toBe("this is [B]important[/B] text");
+  });
+
+  it("leaves bold text plain (markers stripped) when no styler is given", () => {
+    const wrapped = wrapMarkdown("this is **important** text", 80);
+    expect(wrapped).toBe("this is important text");
+  });
+
+  it("strips inline code backticks without styling", () => {
+    const wrapped = wrapMarkdown("call `doThing()` now", 80, (s) => `[B]${s}[/B]`);
+    expect(wrapped).not.toContain("`");
+    expect(wrapped).toBe("call doThing() now");
+  });
+
+  it("wraps list items with a hanging indent instead of merging bullets", () => {
+    const wrapped = wrapMarkdown("- root cause one\n- root cause two", 80);
+    expect(wrapped.split("\n")).toEqual(["- root cause one", "- root cause two"]);
+  });
+
+  it("indents a wrapped list item's continuation line under its text", () => {
+    const wrapped = wrapMarkdown(
+      "- this is a fairly long list item that should wrap across more than one line",
+      30,
+    );
+    const lines = wrapped.split("\n");
+    expect(lines.length).toBeGreaterThan(1);
+    expect(lines[0]?.startsWith("- ")).toBe(true);
+    for (const line of lines.slice(1)) {
+      expect(line.startsWith("  ")).toBe(true);
+      expect(line.startsWith("- ")).toBe(false);
+    }
+  });
+
+  it("keeps a single word longer than width on its own line (no infinite loop)", () => {
+    const longWord = "x".repeat(50);
+    const wrapped = wrapMarkdown(longWord, 10);
+    expect(wrapped).toBe(longWord);
+  });
+
+  it("defaults to the identity styler, never emitting empty output for input text", () => {
+    expect(wrapMarkdown("plain text", 80)).toBe("plain text");
+  });
+});

From 687c8462d5891e267dabadef65a741bb0cb89152 Mon Sep 17 00:00:00 2001
From: Hao Yan <haoyan160@gmail.com>
Date: Fri, 10 Jul 2026 15:20:51 -0600
Subject: [PATCH 2/5] feat(findings): wrap RCA output and surface detector
 verdicts in findings get

---
 src/commands/findings/get.ts        | 63 +++++++++++++++-----
 tests/commands/findings-get.test.ts | 90 ++++++++++++++++++++++++++++-
 2 files changed, 136 insertions(+), 17 deletions(-)

diff --git a/src/commands/findings/get.ts b/src/commands/findings/get.ts
index 00d5ca2..7f43cbe 100644
--- a/src/commands/findings/get.ts
+++ b/src/commands/findings/get.ts
@@ -1,11 +1,15 @@
 import type { Command } from "commander";
 import type { ApiClient, FindingDetail } from "../../api/client.js";
-import { type Writers, CliError, defaultWriters, writeJson } from "../../output.js";
+import { CliError, type Writers, defaultWriters, writeJson } from "../../output.js";
 import { createStyler } from "../../render/style.js";
+import { wrapMarkdown } from "../../render/wrap.js";
 import { formatTimestamp } from "../../util/index.js";
 import { contextFromCommand, requireApiClient } from "../shared.js";
 import { onceOption } from "../traces/list.js";
 
+/** Fallback RCA wrap width when the terminal doesn't report a column count. */
+const DEFAULT_WRAP_WIDTH = 80;
+
 /** Dependencies for the testable core of `findings get`. */
 export interface RunGetDeps {
   client: ApiClient;
@@ -69,6 +73,34 @@ function categoryLabel(template: string | null | undefined): string {
   return CATEGORY_LABELS[template] ?? template.charAt(0).toUpperCase() + template.slice(1);
 }
 
+/**
+ * The detector's own classification, from `result.data.category` (a loose,
+ * detector-defined payload — only a non-empty string `category` key is
+ * trusted). `null` when `data` doesn't carry one, so the caller falls back to
+ * the template-derived label.
+ */
+function dataCategory(data: unknown): string | null {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    return null;
+  }
+  const value = (data as Record<string, unknown>).category;
+  return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+
+/**
+ * The Category line's value: the detector's own conclusion (`data.category`)
+ * when present, annotated with the raw template id for precision, e.g.
+ * `Tool call error (template: failure)`. Falls back to the template-derived
+ * label alone when `data` has no usable category.
+ */
+function detectorCategory(result: FindingDetail["results"][number]): string {
+  const category = dataCategory(result.data);
+  if (category === null) {
+    return categoryLabel(result.template);
+  }
+  return result.template ? `${category} (template: ${result.template})` : category;
+}
+
 function renderFinding(finding: FindingDetail, writers: Writers, timeZone?: string): string {
   const styler = createStyler(writers.out);
   const label = (text: string): string => styler.bold(text);
@@ -81,32 +113,35 @@ function renderFinding(finding: FindingDetail, writers: Writers, timeZone?: stri
   lines.push(`${label("Summary:")}    ${finding.summary}`);
 
   // Per-detector, flush-left: `Detector: <name> (<template>)`, then the unique id
-  // (disambiguates same-named detectors) and the human-readable category.
-  // Multiple detectors are separated by a blank line; per-detector summary/data
-  // stay in `--json` only.
+  // (disambiguates same-named detectors), whether the detector actually fired
+  // (`Identified:`), and the Category line — the detector's own conclusion
+  // (`result.data.category`) when present, else the template-derived label.
+  // Multiple detectors are separated by a blank line; the raw `summary` /
+  // `data` payload stays in `--json` only.
   lines.push("");
   finding.results.forEach((result, i) => {
     if (i > 0) {
       lines.push("");
     }
     const template = result.template ? ` (${result.template})` : "";
-    lines.push(`${label("Detector:")} ${result.detector_name}${template}`);
-    lines.push(`${label("ID:")}       ${result.detector_id}`);
-    lines.push(`${label("Category:")} ${categoryLabel(result.template)}`);
+    lines.push(`${label("Detector:")}   ${result.detector_name}${template}`);
+    lines.push(`${label("ID:")}         ${result.detector_id}`);
+    lines.push(`${label("Identified:")} ${result.identified ? "yes" : "no"}`);
+    lines.push(`${label("Category:")}   ${detectorCategory(result)}`);
   });
 
-  // RCA, flush-left. With a result: a bare `RCA:` header, then the result verbatim
-  // (it already carries its own formatting — usually a markdown list — so no added
-  // bullets, or the markers double up). No RCA → `RCA: none`; an in-progress RCA
-  // with no result yet keeps its status (e.g. `RCA: processing`).
+  // RCA, flush-left. With a result: a bare `RCA:` header, then the result
+  // wrapped to the terminal width with minimal markdown treatment (headings /
+  // `**bold**` / `` `code` `` styled-or-stripped rather than printed literally;
+  // see `render/wrap.ts`). No RCA → `RCA: none`; an in-progress RCA with no
+  // result yet keeps its status (e.g. `RCA: processing`).
   lines.push("");
   if (!finding.rca) {
     lines.push(`${label("RCA:")} none`);
   } else if (finding.rca.result) {
     lines.push(label("RCA:"));
-    for (const resultLine of finding.rca.result.trim().split("\n")) {
-      lines.push(resultLine);
-    }
+    const width = process.stdout.columns ?? DEFAULT_WRAP_WIDTH;
+    lines.push(wrapMarkdown(finding.rca.result.trim(), width, styler.bold));
   } else {
     lines.push(`${label("RCA:")} ${finding.rca.status}`);
   }
diff --git a/tests/commands/findings-get.test.ts b/tests/commands/findings-get.test.ts
index 1179ec6..1b1d5f7 100644
--- a/tests/commands/findings-get.test.ts
+++ b/tests/commands/findings-get.test.ts
@@ -92,16 +92,17 @@ describe("runGet", () => {
     expect(out.data).toContain("ID:");
     expect(out.data).toContain("d1"); // detector id
     expect(out.data).toContain("Category:");
-    expect(out.data).toContain("Hallucination"); // human category label
+    expect(out.data).toContain("Hallucination"); // human category label (no data.category to prefer)
+    expect(out.data).toContain("Identified:");
+    expect(out.data).toContain("yes"); // result.identified surfaced
     expect(out.data).toContain("RCA:");
     expect(out.data).not.toContain("RCA: done"); // status dropped when a result is present
     expect(out.data).toContain("the root cause"); // rca result printed verbatim
     // no per-section RCA header now that there's no structured packet
     expect(out.data).not.toContain("Root cause:");
-    // per-detector summary + data and the "Identified" field are JSON-only now
+    // per-detector summary + raw data payload stay JSON-only
     expect(out.data).not.toContain("unsupported claims");
     expect(out.data).not.toContain('"k": "v"');
-    expect(out.data).not.toContain("Identified");
   });
 
   it("dispatches to getFindingByTrace for --trace", async () => {
@@ -118,6 +119,89 @@ describe("runGet", () => {
     expect(out.data).toContain("tr-9");
   });
 
+  it("prefers the detector's own data.category, noting the raw template in parens", async () => {
+    const { writers: w, out } = writers();
+    await runGet({
+      client: fakeClient({
+        finding: detail({
+          results: [resultItem({ template: "failure", data: { category: "Tool call error" } })],
+        }),
+      }),
+      json: false,
+      writers: w,
+      findingId: "fnd-1",
+    });
+    expect(out.data).toContain("Category:");
+    expect(out.data).toContain("Tool call error (template: failure)");
+  });
+
+  it("falls back to the template label when data has no usable category", async () => {
+    const { writers: w, out } = writers();
+    for (const data of [{ k: "v" }, { category: 42 }, { category: "" }, null, "oops", [1, 2]]) {
+      const localOut = out.data;
+      await runGet({
+        client: fakeClient({
+          finding: detail({ results: [resultItem({ template: "logic", data })] }),
+        }),
+        json: false,
+        writers: w,
+        findingId: "fnd-1",
+      });
+      const added = out.data.slice(localOut.length);
+      expect(added).toContain("Category:");
+      expect(added).toContain("Logic Error");
+      expect(added).not.toContain("(template:"); // fallback form has no parenthetical
+    }
+  });
+
+  it("shows an Identified: no line when a result has identified: false", async () => {
+    const { writers: w, out } = writers();
+    await runGet({
+      client: fakeClient({
+        finding: detail({ results: [resultItem({ identified: false })] }),
+      }),
+      json: false,
+      writers: w,
+      findingId: "fnd-1",
+    });
+    expect(out.data).toContain("Identified:");
+    expect(out.data).toContain("no");
+  });
+
+  it("wraps a long RCA paragraph instead of printing raw hundreds-wide lines", async () => {
+    const longWord = () => "word";
+    const longParagraph = Array.from({ length: 40 }, longWord).join(" ");
+    const { writers: w, out } = writers();
+    await runGet({
+      client: fakeClient({ finding: detail({ rca: { status: "done", result: longParagraph } }) }),
+      json: false,
+      writers: w,
+      findingId: "fnd-1",
+    });
+    const rcaLines = out.data.split("\n").filter((line) => line.length > 0 && !line.includes(":"));
+    for (const line of rcaLines) {
+      expect(line.length).toBeLessThanOrEqual(80); // default fallback width
+    }
+  });
+
+  it("styles-or-strips markdown headings and bold instead of printing them literally", async () => {
+    const { writers: w, out } = writers();
+    await runGet({
+      client: fakeClient({
+        finding: detail({
+          rca: { status: "done", result: "## Root Cause\n\nThe **tool call** failed." },
+        }),
+      }),
+      json: false,
+      writers: w,
+      findingId: "fnd-1",
+    });
+    expect(out.data).not.toContain("##");
+    expect(out.data).not.toContain("**");
+    expect(out.data).toContain("Root Cause");
+    expect(out.data).toContain("tool call");
+  });
+
   it("shows 'RCA: none' and no Root cause line when rca is null", async () => {
     const { writers: w, out } = writers();
     await runGet({

From 5e83333e1dd12fd71174e803b03a41bd1c937e83 Mon Sep 17 00:00:00 2001
From: Hao Yan <haoyan160@gmail.com>
Date: Fri, 10 Jul 2026 15:21:14 -0600
Subject: [PATCH 3/5] feat(findings): end findings get with trace link and
 next-step hints

---
 src/commands/findings/get.ts        | 32 +++++++++++++++++++++--
 tests/commands/findings-get.test.ts | 40 ++++++++++++++++++++++++++---
 2 files changed, 66 insertions(+), 6 deletions(-)

diff --git a/src/commands/findings/get.ts b/src/commands/findings/get.ts
index 7f43cbe..3f8c0fd 100644
--- a/src/commands/findings/get.ts
+++ b/src/commands/findings/get.ts
@@ -49,7 +49,18 @@ export async function runGet(deps: RunGetDeps): Promise<void> {
     return;
   }
 
-  writers.out.write(`${renderFinding(finding, writers, timeZone)}\n`);
+  // Best-effort: fetch the trace purely to get its backend-provided `trace_url`
+  // for the footer link. Never let this fail the command — any error (network,
+  // 404, etc.) degrades to no link, with the next-step hints still shown.
+  let traceUrl: string | null = null;
+  try {
+    const trace = await client.getTrace(finding.trace_id);
+    traceUrl = trace.trace_url;
+  } catch {
+    traceUrl = null;
+  }
+
+  writers.out.write(`${renderFinding(finding, writers, traceUrl, timeZone)}\n`);
 }
 
 /**
@@ -101,7 +112,12 @@ function detectorCategory(result: FindingDetail["results"][number]): string {
   return result.template ? `${category} (template: ${result.template})` : category;
 }
 
-function renderFinding(finding: FindingDetail, writers: Writers, timeZone?: string): string {
+function renderFinding(
+  finding: FindingDetail,
+  writers: Writers,
+  traceUrl: string | null,
+  timeZone?: string,
+): string {
   const styler = createStyler(writers.out);
   const label = (text: string): string => styler.bold(text);
   const lines: string[] = [];
@@ -146,6 +162,18 @@ function renderFinding(finding: FindingDetail, writers: Writers, timeZone?: stri
     lines.push(`${label("RCA:")} ${finding.rca.status}`);
   }
 
+  // Footer: never dead-end. A backend-provided trace link when available (best
+  // effort — never hand-construct a frontend URL), and always the next-step
+  // hints, matching the `styler.warn` idiom `traces get` uses.
+  lines.push("");
+  if (traceUrl !== null) {
+    lines.push(`${label("View in TraceRoot:")} ${styler.link(traceUrl)}`);
+  }
+  lines.push(styler.warn(`run 'traceroot traces get ${finding.trace_id}' for spans and context`));
+  lines.push(
+    styler.warn(`run 'traceroot traces export ${finding.trace_id}' to save a full bundle`),
+  );
+
   return lines.join("\n");
 }
 
diff --git a/tests/commands/findings-get.test.ts b/tests/commands/findings-get.test.ts
index 1b1d5f7..e8a1ded 100644
--- a/tests/commands/findings-get.test.ts
+++ b/tests/commands/findings-get.test.ts
@@ -42,17 +42,30 @@ function detail(over: Partial<FindingDetail> = {}): FindingDetail {
 interface FakeState {
   lastGet?: string;
   lastByTrace?: string;
+  lastGetTrace?: string;
 }
 
 function fakeClient(
-  over: { finding?: FindingDetail; byTrace?: FindingDetail; error?: Error },
+  over: {
+    finding?: FindingDetail;
+    byTrace?: FindingDetail;
+    error?: Error;
+    traceUrl?: string;
+    getTraceError?: Error;
+  },
   state: FakeState = {},
 ): ApiClient {
   const reject = () => Promise.reject(new Error("unused"));
   return {
     whoami: reject,
     listTraces: reject,
-    getTrace: reject,
+    getTrace: (id: string) => {
+      state.lastGetTrace = id;
+      if (over.getTraceError) {
+        return Promise.reject(over.getTraceError);
+      }
+      return Promise.resolve({ trace_url: over.traceUrl ?? "https://app.example/t/1" } as never);
+    },
     exportTrace: reject,
     listDetectors: reject,
     listFindings: reject,
@@ -103,6 +116,10 @@ describe("runGet", () => {
     // per-detector summary + raw data payload stay JSON-only
     expect(out.data).not.toContain("unsupported claims");
     expect(out.data).not.toContain('"k": "v"');
+    // footer: trace link (from the best-effort getTrace) + next-step hints
+    expect(out.data).toContain("https://app.example/t/1");
+    expect(out.data).toContain("traceroot traces get tr-1");
+    expect(out.data).toContain("traceroot traces export tr-1");
   });
 
   it("dispatches to getFindingByTrace for --trace", async () => {
@@ -202,6 +219,19 @@ describe("runGet", () => {
     expect(out.data).toContain("tool call");
   });
 
+  it("omits the trace link (but keeps the next-step hints) when getTrace fails", async () => {
+    const { writers: w, out } = writers();
+    await runGet({
+      client: fakeClient({ finding: detail(), getTraceError: new Error("boom") }),
+      json: false,
+      writers: w,
+      findingId: "fnd-1",
+    });
+    expect(out.data).not.toContain("View in TraceRoot:");
+    expect(out.data).toContain("traceroot traces get tr-1");
+    expect(out.data).toContain("traceroot traces export tr-1");
+  });
+
   it("shows 'RCA: none' and no Root cause line when rca is null", async () => {
     const { writers: w, out } = writers();
     await runGet({
@@ -239,14 +269,16 @@ describe("runGet", () => {
     expect(out.data).not.toContain("- - root cause one"); // no doubled list markers
   });
 
-  it("emits a bare FindingDetail object under --json", async () => {
+  it("emits a bare FindingDetail object under --json, with no trace fetch", async () => {
+    const state: FakeState = {};
     const { writers: w, out } = writers();
     await runGet({
-      client: fakeClient({ finding: detail() }),
+      client: fakeClient({ finding: detail() }, state),
       json: true,
       writers: w,
       findingId: "fnd-1",
     });
+    expect(state.lastGetTrace).toBeUndefined(); // json mode never fetches the trace
     const parsed = JSON.parse(out.data) as Record<string, unknown>;
     expect(parsed.finding_id).toBe("fnd-1");
     expect(parsed.data).toBeUndefined(); // bare object, not a {data,meta} envelope

From 0d4a931ce2a5ac6525d2c0ba50440e4061b06aa5 Mon Sep 17 00:00:00 2001
From: Hao Yan <haoyan160@gmail.com>
Date: Sat, 11 Jul 2026 00:07:09 -0600
Subject: [PATCH 4/5] fix(render): preserve punctuation adjacency around bold
 spans when wrapping

---
 src/render/wrap.ts        | 62 +++++++++++++++++++++++++++++++++------
 tests/render/wrap.test.ts | 29 ++++++++++++++++++
 2 files changed, 82 insertions(+), 9 deletions(-)

diff --git a/src/render/wrap.ts b/src/render/wrap.ts
index 0880d95..0c3b820 100644
--- a/src/render/wrap.ts
+++ b/src/render/wrap.ts
@@ -29,11 +29,23 @@ const LIST_ITEM_RE = /^(\s*)([-*]|\d+\.)\s+(.*)$/;
 const BOLD_SPAN_RE = /\*\*(.+?)\*\*/g;
 const CODE_SPAN_RE = /`([^`]+)`/g;
 
-interface Word {
+/** A run of same-emphasis characters within a {@link Word}. */
+interface Piece {
   plain: string;
   bold: boolean;
 }
 
+/**
+ * One wrappable unit: a maximal run of non-whitespace characters. A word can
+ * span emphasis boundaries (e.g. `(**timeout**),` is one word of three pieces:
+ * `(`, bold `timeout`, `),`), so punctuation glued to a bold span in the source
+ * stays glued in the output. `length` is the visible (unstyled) width.
+ */
+interface Word {
+  pieces: Piece[];
+  length: number;
+}
+
 /** Strips inline code backticks (left plain) then splits `**bold**` spans out. */
 function tokenizeInline(text: string): Array<{ text: string; bold: boolean }> {
   const noCode = text.replace(CODE_SPAN_RE, "$1");
@@ -53,19 +65,51 @@ function tokenizeInline(text: string): Array<{ text: string; bold: boolean }> {
   return tokens;
 }
 
-/** Splits inline-tokenized text into individual words, each carrying its emphasis. */
+/**
+ * Splits inline-tokenized text into words. Whitespace in the SOURCE is the only
+ * word boundary: an emphasis edge with no whitespace around it (e.g.
+ * `**Note**:` or `pre**bold**post`) continues the current word, so no space is
+ * invented next to punctuation when the pieces are rejoined.
+ */
 function toWords(text: string): Word[] {
   const words: Word[] = [];
+  let pieces: Piece[] = [];
+
+  const flushWord = (): void => {
+    if (pieces.length > 0) {
+      words.push({ pieces, length: pieces.reduce((n, p) => n + p.plain.length, 0) });
+      pieces = [];
+    }
+  };
+
   for (const token of tokenizeInline(text)) {
-    for (const plain of token.text.split(/\s+/)) {
-      if (plain.length > 0) {
-        words.push({ plain, bold: token.bold });
+    // Split into alternating whitespace / non-whitespace runs (both kept):
+    // whitespace ends the current word; a non-whitespace run extends it.
+    for (const run of token.text.split(/(\s+)/)) {
+      if (run === "") {
+        continue;
+      }
+      if (/^\s/.test(run)) {
+        flushWord();
+      } else {
+        pieces.push({ plain: run, bold: token.bold });
       }
     }
   }
+  flushWord();
   return words;
 }
 
+/** Renders a word's pieces, applying `style` to the bold ones. */
+function renderWord(word: Word, style: StyleFn): string {
+  return word.pieces.map((p) => (p.bold ? style(p.plain) : p.plain)).join("");
+}
+
+/** A copy of `word` with every piece marked bold (for headings). */
+function boldWord(word: Word): Word {
+  return { pieces: word.pieces.map((p) => ({ ...p, bold: true })), length: word.length };
+}
+
 /**
  * Greedily fills lines up to `width` visible columns (ANSI escapes added by
  * `style` don't count toward width, since wrapping decisions use `plain`
@@ -87,18 +131,18 @@ function fillLines(
 
   const flush = (): void => {
     const prefix = lines.length === 0 ? firstPrefix : contPrefix;
-    lines.push(prefix + current.map((w) => (w.bold ? style(w.plain) : w.plain)).join(" "));
+    lines.push(prefix + current.map((w) => renderWord(w, style)).join(" "));
     current = [];
     currentLen = contPrefix.length;
   };
 
   for (const word of words) {
     const sep = current.length === 0 ? 0 : 1;
-    if (current.length > 0 && currentLen + sep + word.plain.length > safeWidth) {
+    if (current.length > 0 && currentLen + sep + word.length > safeWidth) {
       flush();
     }
     current.push(word);
-    currentLen += (current.length === 1 ? 0 : 1) + word.plain.length;
+    currentLen += (current.length === 1 ? 0 : 1) + word.length;
   }
   if (current.length > 0 || lines.length === 0) {
     flush();
@@ -135,7 +179,7 @@ export function wrapMarkdown(text: string, width: number, bold: StyleFn = (s) =>
     const heading = HEADING_RE.exec(line);
     if (heading) {
       flushParagraph();
-      const words = toWords((heading[2] ?? "").trim()).map((w) => ({ ...w, bold: true }));
+      const words = toWords((heading[2] ?? "").trim()).map(boldWord);
       out.push(...fillLines(words, width, bold, "", ""));
       continue;
     }
diff --git a/tests/render/wrap.test.ts b/tests/render/wrap.test.ts
index 5380236..47685ae 100644
--- a/tests/render/wrap.test.ts
+++ b/tests/render/wrap.test.ts
@@ -51,6 +51,35 @@ describe("wrapMarkdown", () => {
     expect(wrapped).toBe("this is important text");
   });
 
+  it("keeps punctuation glued after a bold span (no invented space)", () => {
+    expect(wrapMarkdown("**Note**: text", 80, (s) => `[B]${s}[/B]`)).toBe("[B]Note[/B]: text");
+    expect(wrapMarkdown("**Note**: text", 80)).toBe("Note: text");
+  });
+
+  it("keeps punctuation glued around a parenthesized bold span", () => {
+    expect(wrapMarkdown("(**timeout**),", 80, (s) => `[B]${s}[/B]`)).toBe("([B]timeout[/B]),");
+    expect(wrapMarkdown("(**timeout**),", 80)).toBe("(timeout),");
+  });
+
+  it("keeps text glued directly before and after a bold span", () => {
+    expect(wrapMarkdown("pre**bold**post", 80, (s) => `[B]${s}[/B]`)).toBe("pre[B]bold[/B]post");
+    expect(wrapMarkdown("pre**bold**post", 80)).toBe("preboldpost");
+  });
+
+  it("still separates the words of a multi-word bold phrase normally", () => {
+    expect(wrapMarkdown("a **bold phrase** here", 80, (s) => `[B]${s}[/B]`)).toBe(
+      "a [B]bold[/B] [B]phrase[/B] here",
+    );
+    expect(wrapMarkdown("a **bold phrase** here", 80)).toBe("a bold phrase here");
+  });
+
+  it("counts a glued word's full visible length when deciding where to wrap", () => {
+    // "(timeout)," is one 10-column word; at width 12 it can't share a line
+    // with "aaa" (3 + 1 + 10 = 14 > 12), so it must wrap as a whole unit.
+    const wrapped = wrapMarkdown("aaa (**timeout**), bb", 12);
+    expect(wrapped.split("\n")).toEqual(["aaa", "(timeout),", "bb"]);
+  });
+
   it("strips inline code backticks without styling", () => {
     const wrapped = wrapMarkdown("call `doThing()` now", 80, (s) => `[B]${s}[/B]`);
     expect(wrapped).not.toContain("`");

From 052478ea308d6d095fd8d76b36314c49936abc26 Mon Sep 17 00:00:00 2001
From: Hao Yan <haoyan160@gmail.com>
Date: Sat, 11 Jul 2026 00:08:23 -0600
Subject: [PATCH 5/5] fix(render): keep indented continuations inside their
 list items

---
 src/render/wrap.ts        | 57 +++++++++++++++++++++++++++++++--------
 tests/render/wrap.test.ts | 31 +++++++++++++++++++++
 2 files changed, 77 insertions(+), 11 deletions(-)

diff --git a/src/render/wrap.ts b/src/render/wrap.ts
index 0c3b820..85dc3b2 100644
--- a/src/render/wrap.ts
+++ b/src/render/wrap.ts
@@ -13,7 +13,8 @@
  *    styled bold.
  *  - `` `code` `` spans: the backticks are stripped (left plain).
  *  - `-`/`*`/`1.`-style list items: wrapped with a hanging indent so
- *    continuation lines align under the item's text rather than the marker.
+ *    continuation lines align under the item's text rather than the marker;
+ *    indented source lines directly under a bullet are folded into that item.
  *  - Plain paragraphs (consecutive non-blank, non-list, non-heading lines):
  *    joined and re-wrapped to `width`; blank lines are preserved as paragraph
  *    separators.
@@ -155,9 +156,17 @@ function fillLines(
  * module doc). `bold` is applied to headings and `**bold**` spans; pass the
  * identity function for a plain-text (no-ANSI) fallback.
  */
+/** An in-progress list item: its marker prefixes plus accumulated text lines. */
+interface OpenListItem {
+  firstPrefix: string;
+  contPrefix: string;
+  text: string[];
+}
+
 export function wrapMarkdown(text: string, width: number, bold: StyleFn = (s) => s): string {
   const out: string[] = [];
   let paragraph: string[] = [];
+  let listItem: OpenListItem | null = null;
 
   const flushParagraph = (): void => {
     if (paragraph.length === 0) {
@@ -168,35 +177,61 @@ export function wrapMarkdown(text: string, width: number, bold: StyleFn = (s) =>
     paragraph = [];
   };
 
+  const flushListItem = (): void => {
+    if (listItem === null) {
+      return;
+    }
+    const joined = listItem.text.join(" ").trim();
+    out.push(...fillLines(toWords(joined), width, bold, listItem.firstPrefix, listItem.contPrefix));
+    listItem = null;
+  };
+
+  // At most one of paragraph / listItem is open at a time; flush both at any
+  // block boundary (blank line, heading, new bullet).
+  const flushBlocks = (): void => {
+    flushParagraph();
+    flushListItem();
+  };
+
   for (const rawLine of text.split("\n")) {
     const line = rawLine.trimEnd();
     if (line.trim() === "") {
-      flushParagraph();
+      flushBlocks();
       out.push("");
       continue;
     }
 
     const heading = HEADING_RE.exec(line);
     if (heading) {
-      flushParagraph();
+      flushBlocks();
       const words = toWords((heading[2] ?? "").trim()).map(boldWord);
       out.push(...fillLines(words, width, bold, "", ""));
       continue;
     }
 
-    const listItem = LIST_ITEM_RE.exec(line);
-    if (listItem) {
-      flushParagraph();
-      const [, indent, marker, rest] = listItem;
-      const firstPrefix = `${indent ?? ""}${marker ?? ""} `;
-      const contPrefix = " ".repeat(firstPrefix.length);
-      out.push(...fillLines(toWords(rest ?? ""), width, bold, firstPrefix, contPrefix));
+    const marker = LIST_ITEM_RE.exec(line);
+    if (marker) {
+      flushBlocks();
+      const firstPrefix = `${marker[1] ?? ""}${marker[2] ?? ""} `;
+      listItem = {
+        firstPrefix,
+        contPrefix: " ".repeat(firstPrefix.length),
+        text: [marker[3] ?? ""],
+      };
+      continue;
+    }
+
+    // An indented line directly under an open bullet continues that item, so
+    // it keeps the item's hanging indent instead of falling out flush-left.
+    if (listItem !== null && /^\s/.test(line)) {
+      listItem.text.push(line.trim());
       continue;
     }
 
+    flushListItem();
     paragraph.push(line.trim());
   }
-  flushParagraph();
+  flushBlocks();
 
   return out.join("\n");
 }
diff --git a/tests/render/wrap.test.ts b/tests/render/wrap.test.ts
index 47685ae..6ba55f8 100644
--- a/tests/render/wrap.test.ts
+++ b/tests/render/wrap.test.ts
@@ -105,6 +105,37 @@ describe("wrapMarkdown", () => {
     }
   });
 
+  it("folds an indented continuation line into its list item's hanging indent", () => {
+    const wrapped = wrapMarkdown("- first\n  continuation", 80);
+    expect(wrapped).toBe("- first continuation");
+  });
+
+  it("wraps a long list item with an indented continuation under the same indent", () => {
+    const wrapped = wrapMarkdown(
+      "- a fairly long first physical line of a bullet\n  and an indented continuation line",
+      30,
+    );
+    const lines = wrapped.split("\n");
+    expect(lines.length).toBeGreaterThan(1);
+    expect(lines[0]?.startsWith("- ")).toBe(true);
+    for (const line of lines.slice(1)) {
+      expect(line.startsWith("  ")).toBe(true); // hanging indent, never flush-left
+      expect(line.startsWith("- ")).toBe(false);
+      expect(line.length).toBeLessThanOrEqual(30);
+    }
+    expect(wrapped.replace(/\s+/g, " ")).toContain("bullet and an indented continuation");
+  });
+
+  it("ends a list item at a non-indented line (back to a plain paragraph)", () => {
+    const wrapped = wrapMarkdown("- item text\nplain paragraph", 80);
+    expect(wrapped.split("\n")).toEqual(["- item text", "plain paragraph"]);
+  });
+
+  it("ends a list item at a blank line", () => {
+    const wrapped = wrapMarkdown("- item text\n\n  indented paragraph", 80);
+    expect(wrapped.split("\n")).toEqual(["- item text", "", "indented paragraph"]);
+  });
+
   it("keeps a single word longer than width on its own line (no infinite loop)", () => {
     const longWord = "x".repeat(50);
     const wrapped = wrapMarkdown(longWord, 10);