feat(terminal): preview images shown by codex viewed image output

Issue 261 reports that the inline terminal image preview added in PR 241
does not trigger for the "Viewed Image" output that the Codex CLI prints
as a tree pointer line followed by a relative path:

    • Viewed Image
      └ app/docs/screenshots/issue-237/proof/pr238-proof-...png

The detector previously only matched absolute paths starting with "/",
and the api fetch validator rejected anything that was not absolute.

This change adds a second detection pass anchored on the tree pointer
glyphs `└` and `├` and a relative path with a supported image extension.
Detection deduplicates against the existing absolute-path pass so plain
absolute paths preceded by a pointer are not double-counted.

The api validator `planTerminalImageFetch` now accepts an optional
`baseDir` and resolves bare relative paths against it. Terminal sessions
remember the project's target dir (e.g. `/home/dev/app`) and pass it as
the base directory when fetching an image, so the relative path printed
by codex resolves to the same file the user is looking at. All previous
safety checks still apply: the base dir itself must be absolute and free
of traversal/control characters, and the joined path is re-validated for
traversal segments and unsafe characters before any docker exec runs.

Tests cover the detection and validator changes including the issue 261
reproduction, alternative `├` pointer, multiple consecutive viewed
images, no-base-dir backwards compatibility, and unsafe-base rejection.

Refs #261

Author: konard

packages/api/src/services/terminal-image-fetch-core.ts

@@ -103,17 +103,39 @@ const normalizeTerminalImagePath = (path: string): TerminalImagePathNormalizatio
   }
 }
 
-export const planTerminalImageFetch = (path: string): TerminalImageFetchPlan => {
+export type TerminalImageFetchOptions = {
+  readonly baseDir?: string
+}
+
+const isAbsolutePosixPath = (value: string): boolean => value.startsWith("/")
+
+const joinBaseDirAndRelativePath = (baseDir: string, relativePath: string): string => {
+  const trimmedBase = baseDir.replace(/\/+$/u, "")
+  return `${trimmedBase}/${relativePath}`
+}
+
+export const planTerminalImageFetch = (
+  path: string,
+  options: TerminalImageFetchOptions = {}
+): TerminalImageFetchPlan => {
   if (typeof path !== "string" || path.length === 0) {
     return { _tag: "InvalidTerminalImageFetch", message: "Image path is required." }
   }
   const normalized = normalizeTerminalImagePath(path)
   if (normalized._tag === "InvalidTerminalImagePath") {
     return { _tag: "InvalidTerminalImageFetch", message: normalized.message }
   }
-  const containerPath = normalized.path
-  if (!containerPath.startsWith("/")) {
-    return { _tag: "InvalidTerminalImageFetch", message: "Image path must be absolute." }
+  const normalizedPath = normalized.path
+  let containerPath = normalizedPath
+  if (!isAbsolutePosixPath(containerPath)) {
+    const baseDir = options.baseDir
+    if (baseDir === undefined || !isAbsolutePosixPath(baseDir)) {
+      return { _tag: "InvalidTerminalImageFetch", message: "Image path must be absolute." }
+    }
+    if (invalidCharacterPattern.test(baseDir) || traversalPattern.test(baseDir)) {
+      return { _tag: "InvalidTerminalImageFetch", message: "Image base directory is invalid." }
+    }
+    containerPath = joinBaseDirAndRelativePath(baseDir, containerPath)
   }
   if (invalidCharacterPattern.test(containerPath)) {
     return { _tag: "InvalidTerminalImageFetch", message: "Image path contains invalid characters." }

packages/api/src/services/terminal-sessions.ts

@@ -59,6 +59,7 @@ type TerminalRecord = {
   projectDisplayName: string
   projectId: string
   projectKey: string
+  projectTargetDir: string
   prepared: ReturnType<typeof prepareProjectSsh>
 }
 
@@ -581,7 +582,8 @@ const registerRecord = (
   projectKey: string,
   projectDisplayName: string,
   prepared: ReturnType<typeof prepareProjectSsh>,
-  projectContainerName: string
+  projectContainerName: string,
+  projectTargetDir: string
 ): TerminalSession => {
   const session: TerminalSession = {
     attachedClients: 0,
@@ -600,6 +602,7 @@ const registerRecord = (
     projectDisplayName,
     projectId,
     projectKey,
+    projectTargetDir,
     pty: null,
     session,
     sockets: new Set<WebSocket>()
@@ -662,7 +665,8 @@ export const createTerminalSession = (
         project.projectKey,
         project.displayName,
         prepared,
-        projectItem.containerName
+        projectItem.containerName,
+        projectItem.targetDir
       )
       yield* _(emitTerminalSessionCreated(projectId, session.id, options.requestId))
       return { project, session }
@@ -681,7 +685,8 @@ export const createTerminalSession = (
       project.projectKey,
       project.displayName,
       prepared,
-      reachableProjectItem.containerName
+      reachableProjectItem.containerName,
+      reachableProjectItem.targetDir
     )
     yield* _(emitTerminalSessionCreated(projectId, session.id, options.requestId))
     yield* _(emitTerminalStatus(projectId, "ssh.post-start", "Post-start self-heal continues in background"))
@@ -786,7 +791,7 @@ export const readProjectTerminalImage = (
         Effect.fail(new ApiNotFoundError({ message: `Terminal session not found: ${sessionId}` }))
       )
     }
-    const plan = planTerminalImageFetch(imagePath)
+    const plan = planTerminalImageFetch(imagePath, { baseDir: record.projectTargetDir })
     if (plan._tag === "InvalidTerminalImageFetch") {
       return yield* _(Effect.fail(new ApiBadRequestError({ message: plan.message })))
     }

packages/api/tests/terminal-image-fetch-core.test.ts

@@ -103,4 +103,53 @@ describe("terminal image fetch core", () => {
       _tag: "InvalidTerminalImageFetch"
     })
   })
+
+  it("resolves a relative path against the provided absolute base directory", () => {
+    expect(
+      planTerminalImageFetch(
+        "app/docs/screenshots/issue-237/proof/pr238-proof-06-skiller-submodule-status.png",
+        { baseDir: "/home/dev" }
+      )
+    ).toEqual({
+      _tag: "ValidTerminalImageFetch",
+      containerPath: "/home/dev/app/docs/screenshots/issue-237/proof/pr238-proof-06-skiller-submodule-status.png",
+      mediaType: "image/png"
+    })
+  })
+
+  it("ignores trailing slashes on the base directory when resolving a relative path", () => {
+    expect(planTerminalImageFetch("photos/cover.jpg", { baseDir: "/home/dev/" })).toEqual({
+      _tag: "ValidTerminalImageFetch",
+      containerPath: "/home/dev/photos/cover.jpg",
+      mediaType: "image/jpeg"
+    })
+  })
+
+  it("still rejects relative paths when no base directory is supplied", () => {
+    expect(planTerminalImageFetch("app/cover.png")).toEqual({
+      _tag: "InvalidTerminalImageFetch",
+      message: "Image path must be absolute."
+    })
+  })
+
+  it("rejects relative paths when the supplied base directory is not absolute", () => {
+    expect(planTerminalImageFetch("app/cover.png", { baseDir: "home/dev" })).toEqual({
+      _tag: "InvalidTerminalImageFetch",
+      message: "Image path must be absolute."
+    })
+  })
+
+  it("rejects an unsafe base directory containing traversal segments", () => {
+    expect(planTerminalImageFetch("cover.png", { baseDir: "/home/dev/../etc" })).toEqual({
+      _tag: "InvalidTerminalImageFetch",
+      message: "Image base directory is invalid."
+    })
+  })
+
+  it("rejects relative paths that contain traversal segments after resolution", () => {
+    expect(planTerminalImageFetch("../etc/cover.png", { baseDir: "/home/dev" })).toMatchObject({
+      _tag: "InvalidTerminalImageFetch",
+      message: "Image path must not contain '.' or '..' segments."
+    })
+  })
 })

packages/app/src/web/terminal-image-paths.ts

@@ -8,6 +8,13 @@ const imagePathPattern = new RegExp(
   "giu"
 )
 
+const treePointerImagePathSource =
+  String.raw`[^\s"'(<>\[\]{}|\\/][^\s"'(<>\[\]{}|\\]*\.(?:${extensionAlternation})`
+const treePointerImagePathPattern = new RegExp(
+  String.raw`(?:^|\s)[└├]\s+(${treePointerImagePathSource})(?=$|[\s"')<>\[\]{}|.,;:?!])`,
+  "giu"
+)
+
 const escapeChar = String.fromCodePoint(0x1B)
 const bellChar = String.fromCodePoint(0x07)
 
@@ -26,22 +33,38 @@ export type TerminalImagePathMatch = {
 export const stripTerminalAnsi = (text: string): string =>
   text.replace(ansiOscPattern, "").replace(ansiCsiPattern, "").replace(ansiOtherEscapePattern, "")
 
-export const detectTerminalImagePathMatches = (text: string): ReadonlyArray<TerminalImagePathMatch> => {
-  const plainText = stripTerminalAnsi(text)
-  const matches: Array<TerminalImagePathMatch> = []
-  for (const match of plainText.matchAll(imagePathPattern)) {
+const collectPatternMatches = (
+  plainText: string,
+  pattern: RegExp,
+  matches: Array<TerminalImagePathMatch>,
+  seenStartIndices: Set<number>
+): void => {
+  for (const match of plainText.matchAll(pattern)) {
     const candidate = match[1]
-    if (candidate !== undefined && candidate.length > 0) {
-      const fullMatch = match[0]
-      const fullStartIndex = match.index
-      const startIndex = fullStartIndex + fullMatch.lastIndexOf(candidate)
-      matches.push({
-        endIndex: startIndex + candidate.length,
-        path: candidate,
-        startIndex
-      })
+    if (candidate === undefined || candidate.length === 0) {
+      continue
     }
+    const fullMatch = match[0]
+    const fullStartIndex = match.index
+    const startIndex = fullStartIndex + fullMatch.lastIndexOf(candidate)
+    if (seenStartIndices.has(startIndex)) {
+      continue
+    }
+    seenStartIndices.add(startIndex)
+    matches.push({
+      endIndex: startIndex + candidate.length,
+      path: candidate,
+      startIndex
+    })
   }
+}
+
+export const detectTerminalImagePathMatches = (text: string): ReadonlyArray<TerminalImagePathMatch> => {
+  const plainText = stripTerminalAnsi(text)
+  const matches: Array<TerminalImagePathMatch> = []
+  const seenStartIndices = new Set<number>()
+  collectPatternMatches(plainText, imagePathPattern, matches, seenStartIndices)
+  collectPatternMatches(plainText, treePointerImagePathPattern, matches, seenStartIndices)
   return matches
 }
 

packages/app/tests/docker-git/terminal-image-paths.test.ts

@@ -98,4 +98,37 @@ describe("terminal image path detection", () => {
     expect(isSupportedTerminalImagePath("/var/data/a.bmp")).toBe(false)
     expect(isSupportedTerminalImagePath("/var/data/a.txt")).toBe(false)
   })
+
+  it("detects relative image paths under a tree pointer (issue 261 viewed image format)", () => {
+    const text = "  └ app/docs/screenshots/issue-237/proof/pr238-proof-06-skiller-submodule-status.png"
+    expect(detectTerminalImagePaths(text)).toEqual([
+      "app/docs/screenshots/issue-237/proof/pr238-proof-06-skiller-submodule-status.png"
+    ])
+  })
+
+  it("detects relative image paths under the alternative branch tree pointer", () => {
+    expect(detectTerminalImagePaths("  ├ assets/cover.jpg")).toEqual(["assets/cover.jpg"])
+  })
+
+  it("detects multiple viewed images across separate lines", () => {
+    const text = [
+      "• Viewed Image",
+      "  └ app/docs/screenshots/issue-237/proof/pr238-proof-06-skiller-submodule-status.png",
+      "",
+      "• Viewed Image",
+      "  └ app/docs/screenshots/issue-237/proof/pr238-proof-09-skiller-submodule-checks.png"
+    ].join("\n")
+    expect(detectTerminalImagePaths(text)).toEqual([
+      "app/docs/screenshots/issue-237/proof/pr238-proof-06-skiller-submodule-status.png",
+      "app/docs/screenshots/issue-237/proof/pr238-proof-09-skiller-submodule-checks.png"
+    ])
+  })
+
+  it("does not duplicate absolute paths preceded by a tree pointer", () => {
+    expect(detectTerminalImagePaths("  └ /var/data/foo.png")).toEqual(["/var/data/foo.png"])
+  })
+
+  it("ignores tree pointers that do not precede an image", () => {
+    expect(detectTerminalImagePaths("  └ Viewed File: notes.txt")).toEqual([])
+  })
 })