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

[konard]

Fixes #261.

Summary

Enables the inline terminal image preview (added in #241, extended in #253) to also fire when the Codex CLI prints its Viewed Image block, which uses a tree pointer line followed by a relative path:

• Viewed Image
  └ app/docs/screenshots/issue-237/proof/pr238-proof-06-skiller-submodule-status.png

Before this change the detector only matched paths starting with /, and the API validator rejected anything that wasn't absolute, so these images were not previewed.

What changed

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

• New regex pattern anchored on the tree pointer glyphs └ and ├ and a relative path with a supported image extension.
• The two patterns (absolute path and tree-pointer + relative path) now run via a shared collector that dedupes by startIndex, so an absolute path that happens to follow a pointer is reported once.

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

• planTerminalImageFetch accepts an optional { baseDir } and resolves bare relative paths against it. The base dir itself must be absolute and free of traversal/control characters; the joined path is re-validated through the existing safety checks (traversal, control chars, supported extensions) before any docker exec runs.

Backend wiring — packages/api/src/services/terminal-sessions.ts

• Terminal sessions now remember the project's targetDir (e.g. /home/dev/app) and pass it as the baseDir when reading the image. This way a relative path like app/docs/... printed inside a session whose cwd is /home/dev resolves to the same file the user is looking at.

Reproduction

The new tests reproduce the issue end-to-end:

• packages/app/tests/docker-git/terminal-image-paths.test.ts
  • detects relative image paths under a tree pointer (issue 261 viewed image format)
  • detects multiple viewed images across separate lines
  • detects relative image paths under the alternative branch tree pointer
  • does not duplicate absolute paths preceded by a tree pointer
  • ignores tree pointers that do not precede an image
• packages/api/tests/terminal-image-fetch-core.test.ts
  • resolves a relative path against the provided absolute base directory
  • ignores trailing slashes on the base directory when resolving a relative path
  • still rejects relative paths when no base directory is supplied
  • rejects relative paths when the supplied base directory is not absolute
  • rejects an unsafe base directory containing traversal segments
  • rejects relative paths that contain traversal segments after resolution

Test plan

• bun run --cwd packages/api typecheck
• bun run --cwd packages/app typecheck
• bun run --cwd packages/api vitest run tests/terminal-image-fetch-core.test.ts — 17/17 pass
• bun run --cwd packages/app vitest run tests/docker-git/terminal-image-paths.test.ts — 18/18 pass
• bun run --cwd packages/app vitest run — 274/274 pass
• bun run --cwd packages/api vitest run — 90/91 pass (one pre-existing failure in tests/projects.test.ts requires a local Docker daemon and is unrelated to this change)

Safety

The path that is finally handed to docker exec is still subject to all of the previously existing checks:

• must be absolute after resolution
• no whitespace or control characters
• no . / .. segments (raw or percent-encoded)
• supported extension only (png, jpg, jpeg, gif, webp)
• 10 MB cap

Additional checks introduced here:

• when baseDir is supplied it must itself be absolute and free of traversal/control characters
• relative paths without a baseDir continue to fail with the same message as before

[konard]

Working session summary

PR #262 is updated and ready for review: #262

Summary of what shipped:

• Frontend (packages/app/src/web/terminal-image-paths.ts): added a regex pass anchored on └/├ tree-pointer lines that captures relative image paths, deduped against the existing absolute-path pass.
• Backend validator (packages/api/src/services/terminal-image-fetch-core.ts): planTerminalImageFetch now accepts an optional baseDir, validated for absoluteness and traversal/control characters, used to resolve bare relative paths through the existing safety checks.
• Wiring (packages/api/src/services/terminal-sessions.ts): the terminal record carries projectTargetDir and passes it as baseDir when fetching images.
• Tests: 5 new frontend cases + 6 new backend cases. All 274 app tests and 90 of 91 api tests pass; the single failing api test is a pre-existing environmental failure (no Docker binary in this sandbox) unrelated to this change.

---

This summary was automatically extracted from the AI working session output.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost: $4.109216

📊 Context and tokens usage:

Claude Opus 4.7: (2 sub-sessions)

1. 115.9K / 1M (12%) input tokens, 22.3K / 128K (17%) output tokens
2. 53.4K / 1M (5%) input tokens, 6.7K / 128K (5%) output tokens

Total: (1.9K new + 151.9K cache writes + 4.6M cache reads) input tokens, 33.8K output tokens, $4.109216 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus
• Model: Claude Opus 4.7 (claude-opus-4-7)

📎 Log file uploaded as Gist (2144KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

✅ Ready to merge

This pull request is now ready to be merged:

• All CI checks have passed
• No merge conflicts
• No pending changes

---

Monitored by hive-mind with --auto-restart-until-mergeable flag