jeo-code 0.7.41 → 0.7.43

package/CHANGELOG.md

@@ -6,6 +6,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
+## [0.7.43] - 2026-07-06
+_TUI inline image DISPLAY (gjc TUI-image parity): jeo could already ATTACH an image to a turn (clipboard paste, drag-drop, `@path`) but never rendered it back — the transcript only ever showed a `⧉ N image(s) attached` count. On a terminal that speaks the kitty graphics protocol (kitty/ghostty/wezterm) or iTerm2's OSC 1337 inline-image protocol, a submitted image now renders as an actual picture directly under the `user` card; every other terminal (Terminal.app, plain xterm, CI/non-TTY) keeps today's text-only behavior unchanged. No native/binary dependency added — Sixel was deliberately left out because producing a sixel stream from arbitrary PNG/JPEG bytes needs a pixel quantizer jeo doesn't have; both implemented protocols decode compressed image bytes themselves._
+
+### Added
+- **`src/tui/terminal-image.ts`** — protocol detection (`detectImageProtocol`, env/TTY-signal based: `KITTY_WINDOW_ID`/`GHOSTTY_RESOURCES_DIR`/`WEZTERM_PANE`/`ITERM_SESSION_ID`/`TERM_PROGRAM`, plus a `$TERM` fallback for tmux/screen-wrapped kitty sessions), dependency-free dimension parsers for PNG/JPEG/GIF/WEBP/BMP (own implementations against each format's public header spec — not ported from gjc's native Rust decoder), aspect-ratio-preserving cell fitting (`fitImageToCells`, never upscales), and encoders for both protocols (`encodeKittyImage` — chunked at the spec's 4096-byte boundary for large payloads; `encodeIterm2Image` — cell-based `width=`/`height=`, never `"auto"`, so jeo's fit math always agrees with what the terminal actually draws). `JEO_IMAGE_PROTOCOL=kitty|iterm2|none` forces a protocol; `JEO_NO_IMAGE_PREVIEW=1` disables inline rendering outright (same shape as `JEO_NO_MULTILINE`/`JEO_NO_MEMORY`).
+- **`src/tui/components/image-preview.ts`** — bridges `ImageAttachment[]` to the protocol layer: renders each attachment as an inline picture when the terminal/format combination supports it, else a dim `⧉ [mediaType] WxH` text caption (kitty's `f=100` decodes PNG only — a JPEG/GIF/WEBP/BMP attachment on a kitty-protocol terminal falls back to caption; iTerm2 decodes any host-native format, so those always render).
+- **`LaunchTui.flushUserCard(text, images?)`** (`src/tui/app.ts`) — the turn-starting user card now accepts the turn's image attachments and, in inline mode on a supporting terminal, flushes them into scrollback via a new `flushImageAttachments` that bypasses `appendLedger`'s width-wrap path entirely (a raw base64 image escape is not text — `wrapTextWithAnsi`/`visibleWidth` would measure its payload as thousands of display columns and mangle it mid-sequence). Wired from `runTurn` in `src/commands/launch.ts` for the real submitted prompt (a skill run's suppressed/compact card, which never carried the user's own attachments, is unaffected).
+
+### Fixed
+- **`truncateToWidth`** (`src/tui/components/width.ts`) now treats an inline-image escape line (detected via the new `isImageEscapeLine`) as opaque and returns it unchanged — a defensive fix for every current and future call site in the truncation pipeline (`terminal.ts#truncate`, the REPL's `logLines`, `Renderer.render`'s live-frame diff): naive column-counting would otherwise slice into a base64 payload mid-sequence, corrupting the image or leaving an unterminated escape that hangs the terminal waiting for its `ESC \`/BEL terminator.
+
+### Verified
+- `bun run typecheck` clean; `bun test` 2424 pass / 0 fail (34 new: `test/terminal-image.test.ts` — protocol detection incl. env-override/disable/tmux-fallback matrix, all 5 dimension parsers against real per-format headers plus malformed-input rejection, cell-fit aspect-ratio math, both encoders incl. kitty's >4096-byte chunking, the `isImageEscapeLine` guard, and the full `renderInlineImage` row-cursor construction proved line-by-line for both protocols; `test/image-preview.test.ts` — multi-attachment stacking and mixed protocol-support fallback; 3 new `LaunchTui.flushUserCard` cases covering a rendered image, a suppressed-terminal fallback with zero escape leakage, and the already-finished no-op).
+- Manual end-to-end smoke test against the real attached terminal (kitty): generated a genuine 4x4 PNG (real zlib-deflated IDAT, not just a magic-byte fixture), ran it through the actual `renderInlineImage` → wrote the resulting kitty APC sequence to `/dev/tty` — completed without hanging or corrupting the terminal. Repeated with an iTerm2 OSC 1337 sequence sent to the same (non-iTerm2) terminal to confirm an unsupported protocol degrades silently (BEL-terminated, ignored) rather than leaking garbage.
+
+## [0.7.42] - 2026-07-06
+_Fixes a genuine infinite hang on "thinking"/"executing" (reported under `jeo --tmux`, but the two root causes are tmux-agnostic): the interactive streaming model call had no absolute wall-clock, and the ~30-minute turn stall budget was a passive check that could never interrupt a blocked await in the first place. A third, lower-confidence but plausible tmux-specific trigger (synchronous TUI frame writes blocking on a backpressured tmux pane) gets a defensive, generic fix too._
+
+### Fixed
+- **The interactive streaming model call had no absolute wall-clock — a connected-but-never-terminating stream hung "thinking" forever.** Unlike `manager.call()`/the non-stream fallback (both wrapped in a hard ~300s `withTimeout`), `manager.stream()` (`src/ai/model-manager.ts`) only armed its overall deadline when `JEO_STREAM_MAX_MS` was explicitly set — off by default — and its idle watchdog re-arms on ANY wire activity, including SSE keepalive/ping bytes and reasoning deltas. A stream that stays connected and periodically emits *something* (provider/proxy keepalives, an endless-reasoning response, a proxy that never forwards the terminal stop event) could re-arm that watchdog forever and never resolve or reject. `streamMaxMs()` now defaults to the same ~300s ceiling `callTimeoutMs()` already uses when `JEO_STREAM_MAX_MS` is unset, giving the streaming path parity with the non-streaming path; explicit overrides (including `0` to disable, for genuinely long-running reasoning use cases) are unchanged.
+- **The `JEO_TURN_MAX_MS` stall budget could never interrupt a hang inside a single blocked model call — the exact scenario it exists to catch.** It was implemented purely as a passive top-of-loop check (`Date.now() - lastProgressAt > turnBudgetMs`); with no armed timer anywhere in `engine.ts`, the check could only run *between* steps — a hang blocked inside one `await` on the model call (e.g. the non-terminating stream above) meant the loop never re-iterated and the budget never fired, even after 30+ minutes. `runAgentLoop` now arms a real `setTimeout` for the remaining budget immediately before each step's model call, aborting a dedicated controller (composed with the turn's existing external signal) when it fires; the timer is cleared and re-armed on every genuine progress reset (executed tool step, mid-turn steering) so a legitimately long multi-step turn is never prematurely cut off, and an internal stall-abort surfaces through the exact same error path as an external Esc/Ctrl-C cancel.
+- **(Defensive, tmux-specific) Live TUI frame writes are now backpressure-aware.** `LaunchTui`'s ~120ms frame tick wrote directly to `process.stdout` every beat; under `--tmux`, `process.stdout` is the tmux pane pty drained by the tmux *server*, and POSIX TTY writes are synchronous — a backpressured/slow-draining tmux client could block the write and freeze the event loop entirely (spinner, timers, and the stall-budget check all stop simultaneously, on whatever phase — "thinking" or "executing" — was current). The frame tick now checks `write()`'s boolean return value and skips scheduled frames while backpressured, resuming automatically on the stream's `'drain'` event, instead of piling up or blocking on synchronous writes. No tmux-detection branching — this is a generic backpressure-safe write pattern that helps regardless of what's on the other end of stdout.
+
+### Verified
+- `bun run typecheck` clean; full suite green.
+- New/updated coverage: `test/round-b.test.ts` (`streamMaxMs()` default/override/disable contract, plus a keepalive-forever stream aborted once the deadline elapses), `test/cycle-and-turn-budget.test.ts` (a never-resolving model call force-aborted once the remaining stall budget elapses, and a regression guard that a normal long multi-step turn is never prematurely aborted), `test/tui-app.test.ts` (the frame tick skips beats under simulated backpressure and resumes on `'drain'`).
+
 ## [0.7.41] - 2026-07-06
 _Refusal-handling workflow audit (follow-up to 0.7.39): fixes a HIGH-severity, long-masked bug where Gemini's real refusal error shape never matched jeo's refusal detector, plus Antigravity's opaque empty-response error, plus a category-aware fail-fast for deterministic ToS-severity refusals that previously spun the full 30-minute stall budget with zero chance of success._
 

package/README.ja.md

@@ -259,11 +259,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.43]** (2026-07-06) — TUI inline image DISPLAY (gjc TUI-image parity): jeo could already ATTACH an image to a turn (clipboard paste, drag-drop, `@path`) but never rendered it back — the transcript only ever showed a `⧉ N image(s) attached` count. On a terminal that speaks the kitty graphics protocol (kitty/ghostty/wezterm) or iTerm2's OSC 1337 inline-image protocol, a submitted image now renders as an actual picture directly under the `user` card; every other terminal (Terminal.app, plain xterm, CI/non-TTY) keeps today's text-only behavior unchanged. No native/binary dependency added — Sixel was deliberately left out because producing a sixel stream from arbitrary PNG/JPEG bytes needs a pixel quantizer jeo doesn't have; both implemented protocols decode compressed image bytes themselves.
+- **[0.7.42]** (2026-07-06) — Fixes a genuine infinite hang on "thinking"/"executing" (reported under `jeo --tmux`, but the two root causes are tmux-agnostic): the interactive streaming model call had no absolute wall-clock, and the ~30-minute turn stall budget was a passive check that could never interrupt a blocked await in the first place. A third, lower-confidence but plausible tmux-specific trigger (synchronous TUI frame writes blocking on a backpressured tmux pane) gets a defensive, generic fix too.
 - **[0.7.41]** (2026-07-06) — Refusal-handling workflow audit (follow-up to 0.7.39): fixes a HIGH-severity, long-masked bug where Gemini's real refusal error shape never matched jeo's refusal detector, plus Antigravity's opaque empty-response error, plus a category-aware fail-fast for deterministic ToS-severity refusals that previously spun the full 30-minute stall budget with zero chance of success.
 - **[0.7.40]** (2026-07-06) — Fixes the release CI's standalone-binary build, broken since before v0.7.31 (last release where that job actually ran and passed) — the `release-binaries` job on v0.7.38 and v0.7.39 both failed silently on every platform target, so neither release has downloadable binaries attached.
 - **[0.7.39]** (2026-07-05) — Fixes an unrecovered Anthropic refusal on Claude Fable 5: the new `stop_details.category: "reasoning_extraction"` refusal shape wasn't recognized, so the turn died with a raw, unfriendly error instead of engaging jeo's existing context-reset refusal-recovery ladder.
-- **[0.7.38]** (2026-07-05) — Ponytail review of 0.7.37's Telegram daemon: closes a real trust-boundary gap (any Telegram user could steer/cancel subagents, not just the paired chat) and a `getUpdates`-failure hot-loop, plus bloat/style cleanup — no new surface area, no config changes.
-- **[0.7.37]** (2026-07-05) — Remote subagent visibility/control over Telegram (gjc Telegram-daemon parity, scoped to jeo's subagent surface only — no forum topics, no inline keyboards, no image attachments; see CHANGELOG 0.7.34 for what jeo intentionally does not replicate from gjc's full notification stack).
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -259,11 +259,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.43]** (2026-07-06) — TUI inline image DISPLAY (gjc TUI-image parity): jeo could already ATTACH an image to a turn (clipboard paste, drag-drop, `@path`) but never rendered it back — the transcript only ever showed a `⧉ N image(s) attached` count. On a terminal that speaks the kitty graphics protocol (kitty/ghostty/wezterm) or iTerm2's OSC 1337 inline-image protocol, a submitted image now renders as an actual picture directly under the `user` card; every other terminal (Terminal.app, plain xterm, CI/non-TTY) keeps today's text-only behavior unchanged. No native/binary dependency added — Sixel was deliberately left out because producing a sixel stream from arbitrary PNG/JPEG bytes needs a pixel quantizer jeo doesn't have; both implemented protocols decode compressed image bytes themselves.
+- **[0.7.42]** (2026-07-06) — Fixes a genuine infinite hang on "thinking"/"executing" (reported under `jeo --tmux`, but the two root causes are tmux-agnostic): the interactive streaming model call had no absolute wall-clock, and the ~30-minute turn stall budget was a passive check that could never interrupt a blocked await in the first place. A third, lower-confidence but plausible tmux-specific trigger (synchronous TUI frame writes blocking on a backpressured tmux pane) gets a defensive, generic fix too.
 - **[0.7.41]** (2026-07-06) — Refusal-handling workflow audit (follow-up to 0.7.39): fixes a HIGH-severity, long-masked bug where Gemini's real refusal error shape never matched jeo's refusal detector, plus Antigravity's opaque empty-response error, plus a category-aware fail-fast for deterministic ToS-severity refusals that previously spun the full 30-minute stall budget with zero chance of success.
 - **[0.7.40]** (2026-07-06) — Fixes the release CI's standalone-binary build, broken since before v0.7.31 (last release where that job actually ran and passed) — the `release-binaries` job on v0.7.38 and v0.7.39 both failed silently on every platform target, so neither release has downloadable binaries attached.
 - **[0.7.39]** (2026-07-05) — Fixes an unrecovered Anthropic refusal on Claude Fable 5: the new `stop_details.category: "reasoning_extraction"` refusal shape wasn't recognized, so the turn died with a raw, unfriendly error instead of engaging jeo's existing context-reset refusal-recovery ladder.
-- **[0.7.38]** (2026-07-05) — Ponytail review of 0.7.37's Telegram daemon: closes a real trust-boundary gap (any Telegram user could steer/cancel subagents, not just the paired chat) and a `getUpdates`-failure hot-loop, plus bloat/style cleanup — no new surface area, no config changes.
-- **[0.7.37]** (2026-07-05) — Remote subagent visibility/control over Telegram (gjc Telegram-daemon parity, scoped to jeo's subagent surface only — no forum topics, no inline keyboards, no image attachments; see CHANGELOG 0.7.34 for what jeo intentionally does not replicate from gjc's full notification stack).
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -261,11 +261,11 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.43]** (2026-07-06) — TUI inline image DISPLAY (gjc TUI-image parity): jeo could already ATTACH an image to a turn (clipboard paste, drag-drop, `@path`) but never rendered it back — the transcript only ever showed a `⧉ N image(s) attached` count. On a terminal that speaks the kitty graphics protocol (kitty/ghostty/wezterm) or iTerm2's OSC 1337 inline-image protocol, a submitted image now renders as an actual picture directly under the `user` card; every other terminal (Terminal.app, plain xterm, CI/non-TTY) keeps today's text-only behavior unchanged. No native/binary dependency added — Sixel was deliberately left out because producing a sixel stream from arbitrary PNG/JPEG bytes needs a pixel quantizer jeo doesn't have; both implemented protocols decode compressed image bytes themselves.
+- **[0.7.42]** (2026-07-06) — Fixes a genuine infinite hang on "thinking"/"executing" (reported under `jeo --tmux`, but the two root causes are tmux-agnostic): the interactive streaming model call had no absolute wall-clock, and the ~30-minute turn stall budget was a passive check that could never interrupt a blocked await in the first place. A third, lower-confidence but plausible tmux-specific trigger (synchronous TUI frame writes blocking on a backpressured tmux pane) gets a defensive, generic fix too.
 - **[0.7.41]** (2026-07-06) — Refusal-handling workflow audit (follow-up to 0.7.39): fixes a HIGH-severity, long-masked bug where Gemini's real refusal error shape never matched jeo's refusal detector, plus Antigravity's opaque empty-response error, plus a category-aware fail-fast for deterministic ToS-severity refusals that previously spun the full 30-minute stall budget with zero chance of success.
 - **[0.7.40]** (2026-07-06) — Fixes the release CI's standalone-binary build, broken since before v0.7.31 (last release where that job actually ran and passed) — the `release-binaries` job on v0.7.38 and v0.7.39 both failed silently on every platform target, so neither release has downloadable binaries attached.
 - **[0.7.39]** (2026-07-05) — Fixes an unrecovered Anthropic refusal on Claude Fable 5: the new `stop_details.category: "reasoning_extraction"` refusal shape wasn't recognized, so the turn died with a raw, unfriendly error instead of engaging jeo's existing context-reset refusal-recovery ladder.
-- **[0.7.38]** (2026-07-05) — Ponytail review of 0.7.37's Telegram daemon: closes a real trust-boundary gap (any Telegram user could steer/cancel subagents, not just the paired chat) and a `getUpdates`-failure hot-loop, plus bloat/style cleanup — no new surface area, no config changes.
-- **[0.7.37]** (2026-07-05) — Remote subagent visibility/control over Telegram (gjc Telegram-daemon parity, scoped to jeo's subagent surface only — no forum topics, no inline keyboards, no image attachments; see CHANGELOG 0.7.34 for what jeo intentionally does not replicate from gjc's full notification stack).
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -259,11 +259,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.43]** (2026-07-06) — TUI inline image DISPLAY (gjc TUI-image parity): jeo could already ATTACH an image to a turn (clipboard paste, drag-drop, `@path`) but never rendered it back — the transcript only ever showed a `⧉ N image(s) attached` count. On a terminal that speaks the kitty graphics protocol (kitty/ghostty/wezterm) or iTerm2's OSC 1337 inline-image protocol, a submitted image now renders as an actual picture directly under the `user` card; every other terminal (Terminal.app, plain xterm, CI/non-TTY) keeps today's text-only behavior unchanged. No native/binary dependency added — Sixel was deliberately left out because producing a sixel stream from arbitrary PNG/JPEG bytes needs a pixel quantizer jeo doesn't have; both implemented protocols decode compressed image bytes themselves.
+- **[0.7.42]** (2026-07-06) — Fixes a genuine infinite hang on "thinking"/"executing" (reported under `jeo --tmux`, but the two root causes are tmux-agnostic): the interactive streaming model call had no absolute wall-clock, and the ~30-minute turn stall budget was a passive check that could never interrupt a blocked await in the first place. A third, lower-confidence but plausible tmux-specific trigger (synchronous TUI frame writes blocking on a backpressured tmux pane) gets a defensive, generic fix too.
 - **[0.7.41]** (2026-07-06) — Refusal-handling workflow audit (follow-up to 0.7.39): fixes a HIGH-severity, long-masked bug where Gemini's real refusal error shape never matched jeo's refusal detector, plus Antigravity's opaque empty-response error, plus a category-aware fail-fast for deterministic ToS-severity refusals that previously spun the full 30-minute stall budget with zero chance of success.
 - **[0.7.40]** (2026-07-06) — Fixes the release CI's standalone-binary build, broken since before v0.7.31 (last release where that job actually ran and passed) — the `release-binaries` job on v0.7.38 and v0.7.39 both failed silently on every platform target, so neither release has downloadable binaries attached.
 - **[0.7.39]** (2026-07-05) — Fixes an unrecovered Anthropic refusal on Claude Fable 5: the new `stop_details.category: "reasoning_extraction"` refusal shape wasn't recognized, so the turn died with a raw, unfriendly error instead of engaging jeo's existing context-reset refusal-recovery ladder.
-- **[0.7.38]** (2026-07-05) — Ponytail review of 0.7.37's Telegram daemon: closes a real trust-boundary gap (any Telegram user could steer/cancel subagents, not just the paired chat) and a `getUpdates`-failure hot-loop, plus bloat/style cleanup — no new surface area, no config changes.
-- **[0.7.37]** (2026-07-05) — Remote subagent visibility/control over Telegram (gjc Telegram-daemon parity, scoped to jeo's subagent surface only — no forum topics, no inline keyboards, no image attachments; see CHANGELOG 0.7.34 for what jeo intentionally does not replicate from gjc's full notification stack).
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.7.41",
+  "version": "0.7.43",
 
 
   "description": "Clean, highly optimized AI coding agent using spec-first loop",

package/src/agent/engine.ts

@@ -330,6 +330,18 @@ export function turnMaxMs(env: Record<string, string | undefined> = process.env)
   }
   return 30 * 60 * 1000;
 }
+/** Minimum delay (ms) before a re-armed stall-interrupt timer may fire — guards against
+ *  a near-zero remaining budget scheduling a same-tick abort that would race the call
+ *  it is meant to protect. */
+const MIN_STALL_ARM_MS = 1_000;
+
+/** Combine the turn's external cancel signal (Esc/Ctrl-C) with an internal one. Mirrors
+ *  the composeAbort/boundedSignal pattern already used in src/ai/model-manager.ts and
+ *  src/auth/flows/google-project.ts — kept local since neither is exported. */
+function composeAbortSignal(outer: AbortSignal | undefined, inner: AbortSignal): AbortSignal {
+  if (!outer) return inner;
+  return typeof AbortSignal.any === "function" ? AbortSignal.any([outer, inner]) : inner;
+}
 
 
 /** Levenshtein distance (small inputs: tool/command names). */
@@ -408,6 +420,26 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
   const turnBudgetMs = turnMaxMs();
   // Reset on every executed tool step and on mid-turn steering.
   let lastProgressAt = turnStartedAt;
+  // Real timer-based interrupt backing the passive check above: JEO_TURN_MAX_MS alone
+  // only re-evaluates at the TOP of the while loop, so it cannot fire while the loop is
+  // parked inside a single blocked model-call await (the exact "genuinely forever" hang
+  // this guards against — a stream that never resolves/rejects). Armed fresh before each
+  // model call for the REMAINING budget and disarmed as soon as that call settles, so it
+  // naturally re-arms on every lastProgressAt reset and never fires after the turn ends.
+  let stallTimer: ReturnType<typeof setTimeout> | undefined;
+  const armStallAbort = (): AbortSignal | undefined => {
+    if (turnBudgetMs <= 0) return opts.signal; // 0 disables the stall budget entirely
+    const ctrl = new AbortController();
+    const remaining = Math.max(MIN_STALL_ARM_MS, turnBudgetMs - (Date.now() - lastProgressAt));
+    stallTimer = setTimeout(() => {
+      ctrl.abort(new Error(`no tool progress for ${Math.round(turnBudgetMs / 60_000)}m — turn stall budget (JEO_TURN_MAX_MS) exceeded without done`));
+    }, remaining);
+    return composeAbortSignal(opts.signal, ctrl.signal);
+  };
+  const disarmStallAbort = () => {
+    if (stallTimer) clearTimeout(stallTimer);
+    stallTimer = undefined;
+  };
   // "steps" | "time" — drives honest wording in the consolidation message.
   let stopKind: "steps" | "time" = "steps";
   let step = 1;
@@ -624,6 +656,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       ev.onReasoningArtifactStream?.(a);
     };
     let responseText: string;
+    const stepSignal = armStallAbort();
     try {
       responseText = await invokeCallLlm(history, {
               jsonMode: true,
@@ -636,7 +669,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
               model: opts.model,
               maxTokens: opts.maxTokens,
               reasoningEffort: opts.reasoningEffort,
-              signal: opts.signal,
+              signal: stepSignal,
               sessionKey: opts.sessionKey,
               onUsage: u => { acc.inputTokens += u.inputTokens ?? 0; acc.outputTokens += u.outputTokens ?? 0; sawUsage = true; },
               onToken,
@@ -652,7 +685,9 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
                 ev.onNotice?.(`${what} — auto-retry #${attempt} in ${wait}s`);
               },
             });
+      disarmStallAbort(); // call settled successfully — the stall interrupt no longer applies
     } catch (err) {
+      disarmStallAbort(); // clear before classifying: a fired stall-abort must not linger past this call
       // Reactive context recovery: trim older tool results in place and retry the
       // SAME step once. The provider's overflow signal beats the local estimate;
       // a second overflow (or nothing left to trim) surfaces the friendly error.

package/src/ai/model-manager.ts

@@ -576,11 +576,20 @@ async function nextMaybeIdle(iter: AsyncIterator<string>, watchdog?: Promise<nev
   return Promise.race([iter.next(), watchdog]);
 }
 
-/** Opt-in overall stream wall-clock from the environment; undefined = off (default). */
+/** Overall stream wall-clock from the environment. Defaults to the same hard bound as
+ *  callTimeoutMs() (DEFAULT_CALL_TIMEOUT_MS) so the streaming path has parity with the
+ *  non-streaming call()/fallback path — a stream that stays connected and keeps emitting
+ *  SOMETHING (SSE keepalives, reasoning deltas) re-arms the per-chunk idle watchdog
+ *  forever and would otherwise never resolve or reject. JEO_STREAM_MAX_MS explicitly set
+ *  to a positive number overrides the default; explicitly set to 0 disables the overall
+ *  deadline entirely (mirrors JEO_TURN_MAX_MS's own 0-disables convention) for advanced
+ *  users with genuinely long-running legitimate reasoning models. */
 export function streamMaxMs(env?: Record<string, string | undefined>): number | undefined {
   const raw = jeoEnv("STREAM_MAX_MS", env);
-  const n = raw !== undefined ? parseInt(raw, 10) : NaN;
-  return Number.isFinite(n) && n > 0 ? n : undefined;
+  if (raw === undefined || raw === "") return DEFAULT_CALL_TIMEOUT_MS;
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 0) return DEFAULT_CALL_TIMEOUT_MS;
+  return n === 0 ? undefined : n;
 }
 
 /** Per-chunk idle cap (ms) from the environment, falling back to the built-in default.

package/src/commands/launch.ts

@@ -938,7 +938,11 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
       // in scrollback. opts.userCard overrides it: null suppresses the card entirely
       // (skill runs), a string shows a compact label instead of the raw input.
       const cardText = opts?.userCard === undefined ? userInput : opts.userCard;
-      if (tui && cardText && cardText.trim()) tui.flushUserCard(cardText);
+      // Images render alongside the card only for the real prompt (undefined
+      // userCard) — a skill run's compact/suppressed card never carried the
+      // user's own attachments in the first place (buildSkillTask calls above
+      // never pass `images`), so there is nothing to show either way.
+      if (tui && cardText && cardText.trim()) tui.flushUserCard(cardText, opts?.userCard === undefined ? images : undefined);
       tui?.setContextUsage(historyTokens(history), contextTokens);
 
       // Per-turn steering inbox (gjc parity): additional queries typed mid-turn land

package/src/tui/app.ts

@@ -38,6 +38,9 @@ import { formatDuration, formatUsage } from "./components/duration";
 import { renderHud, type JeoPhase } from "./components/hud";
 import { formatTodoWriteCard } from "./components/todo-card";
 import { renderInputBox, type HighlightRange } from "./components/input-box";
+import { renderImageAttachments } from "./components/image-preview";
+import { detectImageProtocol } from "./terminal-image";
+import type { ImageAttachment } from "../ai/types";
 import { jeoEnv } from "../util/env";
 import chalk from "chalk";
 
@@ -54,7 +57,7 @@ export interface LaunchTuiOptions {
   /** Resolved provider name for the footer (anthropic / openai / gemini / ollama). */
   provider?: string;
   sessionId?: string;
-  write?: (s: string) => void;
+  write?: (s: string) => void | boolean;
   /** Step budget for this turn; drives the footer's `step N/M` denominator. */
   maxSteps?: number;
   /** Whether to treat the output as a TTY (drives alt-screen use). Defaults to isTTY(). */
@@ -213,6 +216,13 @@ export class LaunchTui {
   private mutationGuarded = false;
   private finished = false;
   private timer: ReturnType<typeof setInterval> | undefined;
+  // Backpressure-aware live frame emission: process.stdout.write() returns false when the
+  // internal buffer is over the high-water mark (e.g. a tmux client draining slowly, or
+  // any slow consumer on the other end of stdout). Skipping scheduled frames while this is
+  // true — instead of piling up an unbounded queue of synchronous writes or blocking the
+  // event loop waiting on 'drain' — keeps the render loop responsive and non-blocking.
+  // Generic and tmux-agnostic: helps regardless of what's downstream of stdout.
+  private stdoutBackpressured = false;
   // Resize handling (gjc-style responsiveness): repaint IMMEDIATELY on the first event
   // so a deliberate resize never lags, then cap follow-ups to ~30fps so a drag-resize
   // tracks the cursor live (instead of staying stale until the drag pauses — the lag a
@@ -345,7 +355,19 @@ export class LaunchTui {
   private readonly thinkingLevel?: string;
 
   constructor(opts: LaunchTuiOptions) {
-    this.write = opts.write ?? ((s: string) => process.stdout.write(s));
+    // Backpressure-aware wrapper around the underlying writer (real stdout, or the
+    // caller-injected `write` used by tests). An explicit `false` return (Node/Bun stream
+    // convention: internal buffer over the high-water mark) arms the flag the live-frame
+    // interval checks; a real 'drain' event (asynchronous — never awaited here) clears it.
+    // A test double returning `undefined` (the existing convention throughout this file's
+    // tests) never trips the check, so non-backpressure-aware callers are unaffected.
+    const rawWrite = opts.write ?? ((s: string) => process.stdout.write(s));
+    this.write = (s: string) => {
+      if (rawWrite(s) === false && !this.stdoutBackpressured) {
+        this.stdoutBackpressured = true;
+        process.stdout.once("drain", () => { this.stdoutBackpressured = false; });
+      }
+    };
     this.tty = opts.tty ?? isTTY();
     this.inline = this.tty && jeoEnv("TUI_ALT_SCREEN") !== "1";
     // Row reservation is only needed (and only safe) for the inline main-buffer frame;
@@ -768,13 +790,35 @@ export class LaunchTui {
 
   /** Flush a `user` card into scrollback so a submitted query stays visible there
    *  (gjc parity), instead of only as the transient HUD turn-title / a status notice.
-   *  Shared by the prompt that STARTS a turn and the mid-turn steering flush. */
-  flushUserCard(text: string): void {
+   *  Shared by the prompt that STARTS a turn and the mid-turn steering flush.
+   *  `images` (clipboard/drag-drop/file-path attachments on THIS prompt) render as
+   *  an inline picture directly below the card on a terminal that speaks the kitty
+   *  or iTerm2 graphics protocol (gjc TUI-image parity); every other terminal, the
+   *  alt screen, and non-TTY output keep the existing text-only card unchanged. */
+  flushUserCard(text: string, images?: ImageAttachment[]): void {
     const t = (text ?? "").trim();
     if (!t || this.finished) return;
     const cols = Math.max(20, size().cols - 1);
     const lines = this.renderUserCard(t, cols);
     if (lines.length) this.appendLedger(lines.join("\n"), "card");
+    if (images?.length) this.flushImageAttachments(images, cols);
+  }
+
+  /** Render `images` (see {@link flushUserCard}) straight into scrollback via
+   *  `insertAbove`, bypassing `appendLedger`'s width-wrap path: an inline image
+   *  escape sequence is not text — `wrapTextWithAnsi`/`visibleWidth` would measure
+   *  its base64 payload as thousands of display columns and mangle it. Inline mode
+   *  only (alt screen has no scrollback to flush into; non-TTY has no terminal to
+   *  draw into) — every other mode already shows the "N image(s) attached" note
+   *  inline in the prompt text itself via `[image #N]` tags, unchanged. */
+  private flushImageAttachments(images: ImageAttachment[], cols: number): void {
+    if (!this.inline || this.finished) return;
+    const protocol = detectImageProtocol(process.env, this.tty);
+    const muted = this.theme.color ? chalk.dim : (s: string) => s;
+    const lines = renderImageAttachments(images, { cols, protocol, muted });
+    if (lines.length === 0) return;
+    this.recordActivity(`⧉ ${images.length} image(s) rendered`);
+    this.renderer.insertAbove(`${lines.join("\n")}\n`);
   }
 
   /** Mid-turn steering query → a `user` card in scrollback (accepted input that is
@@ -1040,6 +1084,11 @@ export class LaunchTui {
     this.timer = setInterval(() => {
       try {
         this.tickCount++;
+        // Backpressure: skip this scheduled frame entirely rather than piling up writes
+        // or blocking on 'drain' — the tick simply resumes once the writer drains (see
+        // the this.write wrapper above). The spinner/tickCount stay static for the
+        // skipped beat(s), matching the frozen frame this defers presenting.
+        if (this.stdoutBackpressured) return;
         // Self-healing resync: every ~3s drop the differential baseline so the next
         // draw rewrites EVERY line. Any screen corruption (stray child output, wheel
         // noise, terminal glitches) is repaired automatically without user action.

package/src/tui/components/image-preview.ts

@@ -0,0 +1,49 @@
+/**
+ * User-attached image → scrollback block. Bridges `ImageAttachment[]` (the
+ * clipboard/drag-drop/file-path attachments already supported by
+ * `util/file-attachment.ts` and `util/clipboard-image.ts`) to the inline-image
+ * escape sequences in `terminal-image.ts`, producing one stacked block ready for
+ * `Renderer.insertAbove` — gjc TUI-parity: jeo could already ATTACH an image to a
+ * turn, this is the missing DISPLAY half (the transcript previously showed only a
+ * `⧉ N image(s) attached` count, never the picture itself).
+ */
+import type { ImageAttachment } from "../../ai/types";
+import { detectImageProtocol, renderInlineImage, type ImageProtocol } from "../terminal-image";
+
+export interface ImagePreviewOptions {
+  /** Terminal columns available for the block (already margin-adjusted by the
+   *  caller, same convention as every other card renderer in `tui/app.ts`). */
+  cols: number;
+  /** Cap on how many terminal rows a SINGLE image may occupy — keeps one huge
+   *  screenshot from pushing the whole scrollback off-screen. */
+  maxRowsPerImage?: number;
+  /** Pre-detected protocol (tests / callers that already resolved it once per
+   *  process). Defaults to live detection against `process.env`/`process.stdout`. */
+  protocol?: ImageProtocol;
+  /** Dim/muted painter applied to text captions (fallback path) so they read as
+   *  secondary content, matching the rest of the TUI's caption styling. */
+  muted?: (s: string) => string;
+}
+
+/**
+ * Render every attachment as a stacked block of lines: an inline picture when the
+ * terminal protocol + format support it, else a dim text caption. Multiple
+ * attachments stack top-to-bottom, each keeping its own row reservation — see
+ * `terminal-image.ts#renderInlineImage` for why each image is self-contained
+ * (no dependency on being first/last in the stack).
+ */
+export function renderImageAttachments(images: ImageAttachment[], opts: ImagePreviewOptions): string[] {
+  if (images.length === 0) return [];
+  const protocol = opts.protocol ?? detectImageProtocol(process.env, !!process.stdout.isTTY);
+  const maxColumns = Math.max(10, Math.min(60, opts.cols - 4));
+  const maxRows = Math.max(4, opts.maxRowsPerImage ?? 20);
+  const muted = opts.muted ?? ((s: string) => s);
+
+  const lines: string[] = [];
+  for (const img of images) {
+    const result = renderInlineImage(img, protocol, { maxColumns, maxRows });
+    if (result.rendered) lines.push(...result.lines);
+    else lines.push(...result.lines.map(muted));
+  }
+  return lines;
+}

package/src/tui/components/width.ts

@@ -9,6 +9,7 @@
  * color escapes verbatim (never counting them) so colored/CJK lines truncate and
  * wrap without tearing an escape or miscounting a wide glyph.
  */
+import { isImageEscapeLine } from "../terminal-image";
 
 const TAB_STOP = 8;
 // Sticky SGR matcher: scan a heavily color-escaped line in O(n) without slicing.
@@ -96,6 +97,14 @@ export function visibleWidth(s: string): number {
 export function truncateToWidth(s: string, cols: number): string {
   const limit = Math.max(0, cols);
   if (limit === 0) return "";
+  // An inline terminal-image escape (Kitty APC / iTerm2 OSC 1337, see
+  // `../terminal-image.ts#isImageEscapeLine`) is not text: its "width" by a naive
+  // column count is the base64 payload length (thousands of columns), and slicing
+  // into the payload corrupts the image or leaves an unterminated escape that
+  // hangs the terminal waiting for its `ESC \\`/BEL terminator. The image was
+  // already fit to the caller's column budget when the sequence was BUILT, so the
+  // correct "truncation" here is always a no-op.
+  if (isImageEscapeLine(s)) return s;
   // Fast path: no escapes, no wide chars, no tabs → plain slice by length.
   if (!s.includes("\x1b") && !/[\t\u0300-\uffff]/.test(s) && !/[\u{10000}-\u{10ffff}]/u.test(s)) {
     return s.length <= limit ? s : s.slice(0, limit);

package/src/tui/terminal-image.ts

@@ -0,0 +1,363 @@
+/**
+ * Inline terminal image protocols (gjc TUI-parity): detect whether the attached
+ * terminal can render a real bitmap inline, and encode `ImageAttachment` bytes into
+ * the matching escape sequence — Kitty graphics protocol (also implemented by
+ * Ghostty and WezTerm) or iTerm2's OSC 1337 inline-image protocol. Sixel is
+ * intentionally NOT implemented: producing a sixel stream from arbitrary PNG/JPEG
+ * bytes needs a pixel quantizer, which would be jeo's first native/binary
+ * dependency — every terminal jeo targets (kitty/ghostty/wezterm/iTerm2) already
+ * speaks one of the two protocols below, so a text caption is the correct fallback
+ * everywhere else (Terminal.app, most Linux console/VTE terminals, CI/non-TTY).
+ *
+ * Callers never need to know which protocol was chosen: {@link renderInlineImage}
+ * returns either a ready-to-write escape block or `null` (caller shows the caption).
+ */
+// Inlined (not imported from `./terminal`) to keep this module free to be imported
+// FROM `./components/width` (see `isImageEscapeLine` below) without a cycle:
+// `./terminal` itself imports `truncateToWidth` from `./components/width`.
+function cursorUp(n: number): string {
+  return n > 0 ? `\x1b[${n}A` : "";
+}
+
+export enum ImageProtocol {
+  Kitty = "kitty",
+  Iterm2 = "iterm2",
+  None = "none",
+}
+
+export type EnvLike = Record<string, string | undefined>;
+
+export interface PixelDimensions {
+  widthPx: number;
+  heightPx: number;
+}
+
+export interface CellPixelSize {
+  widthPx: number;
+  heightPx: number;
+}
+
+/** `JEO_IMAGE_PROTOCOL=kitty|iterm2|none` forces the protocol regardless of
+ *  detection — the escape hatch for a misdetected terminal or a multiplexer that
+ *  doesn't forward `TERM_PROGRAM`. Unrecognized values are ignored (fall through
+ *  to detection) rather than silently disabling images. */
+function forcedProtocol(env: EnvLike): ImageProtocol | undefined {
+  const raw = env.JEO_IMAGE_PROTOCOL?.trim().toLowerCase();
+  if (!raw) return undefined;
+  if (raw === "kitty") return ImageProtocol.Kitty;
+  if (raw === "iterm2" || raw === "iterm") return ImageProtocol.Iterm2;
+  if (raw === "none" || raw === "off" || raw === "0" || raw === "false") return ImageProtocol.None;
+  return undefined;
+}
+
+/** `JEO_NO_IMAGE_PREVIEW=1` disables inline image rendering outright (same shape
+ *  as `JEO_NO_MULTILINE`/`JEO_NO_MEMORY`) — every attachment falls back to its text
+ *  caption. Distinct from `JEO_IMAGE_PROTOCOL=none` only in intent/discoverability;
+ *  both end at {@link ImageProtocol.None}. */
+export function imagePreviewDisabled(env: EnvLike = process.env): boolean {
+  const v = env.JEO_NO_IMAGE_PREVIEW;
+  return v === "1" || v === "true";
+}
+
+/**
+ * Detect the inline-image protocol the attached terminal speaks, from environment
+ * signals alone (no terminal query round-trip — keeps startup synchronous and
+ * side-effect-free, matching how `detectColorLevel` works). `env`/`isTty` are
+ * injectable for tests.
+ */
+export function detectImageProtocol(env: EnvLike = process.env, isTty = false): ImageProtocol {
+  if (imagePreviewDisabled(env)) return ImageProtocol.None;
+  const forced = forcedProtocol(env);
+  if (forced !== undefined) return forced;
+  if (!isTty) return ImageProtocol.None;
+
+  if (env.KITTY_WINDOW_ID) return ImageProtocol.Kitty;
+  if (env.GHOSTTY_RESOURCES_DIR) return ImageProtocol.Kitty; // Ghostty speaks the kitty graphics protocol
+  if (env.WEZTERM_PANE) return ImageProtocol.Kitty; // WezTerm speaks the kitty graphics protocol
+  if (env.ITERM_SESSION_ID) return ImageProtocol.Iterm2;
+
+  const termProgram = (env.TERM_PROGRAM ?? "").toLowerCase();
+  if (termProgram === "kitty") return ImageProtocol.Kitty;
+  if (termProgram === "ghostty" || termProgram === "wezterm") return ImageProtocol.Kitty;
+  if (termProgram === "iterm.app") return ImageProtocol.Iterm2;
+
+  // tmux/screen strip TERM_PROGRAM but usually preserve $TERM as "tmux-256color" /
+  // "screen.xterm-kitty" etc. — fall back to sniffing $TERM for a kitty signature
+  // (gjc parity: the same fallback it applies for tmux-wrapped kitty sessions).
+  const term = (env.TERM ?? "").toLowerCase();
+  if (term.includes("kitty")) return ImageProtocol.Kitty;
+  if ((term.startsWith("tmux") || term.startsWith("screen")) && env.KITTY_LISTEN_ON) return ImageProtocol.Kitty;
+
+  return ImageProtocol.None;
+}
+
+let cellPixelSizeOverride: CellPixelSize | undefined;
+
+/** Cell pixel size used to convert a target column/row box into scaled pixels for
+ *  the fit computation. jeo does not query the terminal for real font metrics (that
+ *  needs a synchronous escape round-trip on startup, which risks hanging on a
+ *  terminal that never answers) — 9x18 is the common monospace-at-default-size
+ *  figure (matches gjc's default) and only affects the ASPECT-RATIO fit, not
+ *  correctness: a wrong guess makes the preview a bit larger/smaller, never
+ *  corrupts output. Overridable for unusually large/small fonts. */
+export function getCellPixelSize(env: EnvLike = process.env): CellPixelSize {
+  if (cellPixelSizeOverride) return cellPixelSizeOverride;
+  const w = Number.parseInt(env.JEO_CELL_WIDTH_PX ?? "", 10);
+  const h = Number.parseInt(env.JEO_CELL_HEIGHT_PX ?? "", 10);
+  return {
+    widthPx: Number.isFinite(w) && w > 0 ? w : 9,
+    heightPx: Number.isFinite(h) && h > 0 ? h : 18,
+  };
+}
+
+/** Test-only: pin the cell size so fit-math assertions don't depend on env parsing. */
+export function setCellPixelSizeForTest(size: CellPixelSize | undefined): void {
+  cellPixelSizeOverride = size;
+}
+
+/** PNG: 8-byte signature + 4-byte length + "IHDR" (4 bytes) precede a big-endian
+ *  `{width, height}` u32 pair — the format's own spec, fixed offsets 16 and 20. */
+export function getPngDimensions(bytes: Uint8Array): PixelDimensions | null {
+  if (bytes.length < 24) return null;
+  if (bytes[0] !== 0x89 || bytes[1] !== 0x50 || bytes[2] !== 0x4e || bytes[3] !== 0x47) return null;
+  const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return { widthPx: buf.readUInt32BE(16), heightPx: buf.readUInt32BE(20) };
+}
+
+/** JPEG: scan markers for the first SOFn (0xC0-0xC3, 0xC5-0xC7, 0xC9-0xCB, 0xCD-0xCF —
+ *  excludes 0xC4/0xC8/0xCC, which are DHT/JPG/DAC, not frame headers); height/width
+ *  are big-endian u16 at offsets 5/7 into that marker's segment. */
+export function getJpegDimensions(bytes: Uint8Array): PixelDimensions | null {
+  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) return null;
+  const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let offset = 2;
+  while (offset + 9 < buf.length) {
+    if (buf[offset] !== 0xff) { offset++; continue; }
+    const marker = buf[offset + 1]!;
+    const isSof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+    if (isSof) return { heightPx: buf.readUInt16BE(offset + 5), widthPx: buf.readUInt16BE(offset + 7) };
+    if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd9)) { offset += 2; continue; } // no-length markers
+    const segLen = buf.readUInt16BE(offset + 2);
+    if (segLen < 2) return null;
+    offset += 2 + segLen;
+  }
+  return null;
+}
+
+/** GIF87a/89a: little-endian u16 width/height at fixed offsets 6/8 in the Logical
+ *  Screen Descriptor, right after the 6-byte signature. */
+export function getGifDimensions(bytes: Uint8Array): PixelDimensions | null {
+  if (bytes.length < 10) return null;
+  const sig = Buffer.from(bytes.slice(0, 6)).toString("ascii");
+  if (sig !== "GIF87a" && sig !== "GIF89a") return null;
+  const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return { widthPx: buf.readUInt16LE(6), heightPx: buf.readUInt16LE(8) };
+}
+
+/** WebP: RIFF container: dimensions live in the first sub-chunk, whose layout
+ *  differs by codec — VP8 (lossy, 10-bit width/height at a fixed offset), VP8L
+ *  (lossless, 14-bit packed into a little-endian u32), VP8X (extended, 24-bit
+ *  little-endian triples, stored as size-1). */
+export function getWebpDimensions(bytes: Uint8Array): PixelDimensions | null {
+  if (bytes.length < 30) return null;
+  const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (buf.toString("ascii", 0, 4) !== "RIFF" || buf.toString("ascii", 8, 12) !== "WEBP") return null;
+  const chunk = buf.toString("ascii", 12, 16);
+  if (chunk === "VP8 ") {
+    return { widthPx: buf.readUInt16LE(26) & 0x3fff, heightPx: buf.readUInt16LE(28) & 0x3fff };
+  }
+  if (chunk === "VP8L") {
+    if (bytes.length < 25) return null;
+    const bits = buf.readUInt32LE(21);
+    return { widthPx: (bits & 0x3fff) + 1, heightPx: ((bits >> 14) & 0x3fff) + 1 };
+  }
+  if (chunk === "VP8X") {
+    return {
+      widthPx: (buf[24]! | (buf[25]! << 8) | (buf[26]! << 16)) + 1,
+      heightPx: (buf[27]! | (buf[28]! << 8) | (buf[29]! << 16)) + 1,
+    };
+  }
+  return null;
+}
+
+/** BMP: "BM" signature, then a DIB header whose size (u32 at offset 14) picks the
+ *  layout — the legacy 12-byte BITMAPCOREHEADER stores 16-bit dimensions at
+ *  offset 18/20; every later header (BITMAPINFOHEADER=40 and newer) stores 32-bit
+ *  signed dimensions at 18/22 (a negative height means top-down — take `abs`). */
+export function getBmpDimensions(bytes: Uint8Array): PixelDimensions | null {
+  if (bytes.length < 26 || bytes[0] !== 0x42 || bytes[1] !== 0x4d) return null;
+  const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const dibSize = buf.readUInt32LE(14);
+  if (dibSize === 12) {
+    if (bytes.length < 22) return null;
+    return { widthPx: buf.readUInt16LE(18), heightPx: buf.readUInt16LE(20) };
+  }
+  if (bytes.length < 26) return null;
+  return { widthPx: buf.readInt32LE(18), heightPx: Math.abs(buf.readInt32LE(22)) };
+}
+
+/** Dispatch to the matching parser by IANA media type; `null` when unrecognized or
+ *  the bytes are too short/malformed to carry a header. */
+export function getImageDimensions(bytes: Uint8Array, mediaType: string): PixelDimensions | null {
+  switch (mediaType) {
+    case "image/png": return getPngDimensions(bytes);
+    case "image/jpeg": return getJpegDimensions(bytes);
+    case "image/gif": return getGifDimensions(bytes);
+    case "image/webp": return getWebpDimensions(bytes);
+    case "image/bmp": return getBmpDimensions(bytes);
+    default: return null;
+  }
+}
+
+export interface ImageFit {
+  columns: number;
+  rows: number;
+}
+
+/**
+ * Scale `dims` to fit within `maxColumns` x `maxRows` terminal cells, preserving
+ * aspect ratio (letterboxed, never cropped/stretched). Falls back to a 1:1
+ * guess (one column per ~1 cell-width of pixels) when `dims` is unknown so a
+ * dimension-less image (parser miss) still gets a sane box instead of a crash.
+ */
+export function fitImageToCells(dims: PixelDimensions | null, maxColumns: number, maxRows: number, cell: CellPixelSize): ImageFit {
+  const maxCols = Math.max(1, Math.floor(maxColumns));
+  const maxRowsClamped = Math.max(1, Math.floor(maxRows));
+  if (!dims || dims.widthPx <= 0 || dims.heightPx <= 0) {
+    return { columns: maxCols, rows: maxRowsClamped };
+  }
+  const maxWidthPx = maxCols * cell.widthPx;
+  const maxHeightPx = maxRowsClamped * cell.heightPx;
+  const scale = Math.min(maxWidthPx / dims.widthPx, maxHeightPx / dims.heightPx, 1);
+  const fittedWidthPx = dims.widthPx * scale;
+  const fittedHeightPx = dims.heightPx * scale;
+  return {
+    columns: Math.max(1, Math.min(maxCols, Math.round(fittedWidthPx / cell.widthPx))),
+    rows: Math.max(1, Math.min(maxRowsClamped, Math.ceil(fittedHeightPx / cell.heightPx))),
+  };
+}
+
+const KITTY_CHUNK_SIZE = 4096;
+
+/**
+ * Encode PNG bytes (base64) as a kitty graphics protocol APC sequence, chunked at
+ * 4096 base64 bytes per the spec (a payload above that MUST be split across
+ * multiple `m=1`-continued transmissions, terminated by one `m=0`). `a=T`
+ * (transmit-and-display in one step), `f=100` (PNG — the only compressed format
+ * the protocol decodes itself), `q=2` (suppress the terminal's OK/error response,
+ * which jeo never reads).
+ */
+export function encodeKittyImage(base64Png: string, fit: ImageFit): string {
+  const params = `a=T,f=100,q=2,c=${fit.columns},r=${fit.rows}`;
+  if (base64Png.length <= KITTY_CHUNK_SIZE) {
+    return `\x1b_G${params};${base64Png}\x1b\\`;
+  }
+  const parts: string[] = [];
+  for (let offset = 0; offset < base64Png.length; offset += KITTY_CHUNK_SIZE) {
+    const chunk = base64Png.slice(offset, offset + KITTY_CHUNK_SIZE);
+    const isFirst = offset === 0;
+    const isLast = offset + KITTY_CHUNK_SIZE >= base64Png.length;
+    const head = isFirst ? `${params},m=${isLast ? 0 : 1}` : `m=${isLast ? 0 : 1}`;
+    parts.push(`\x1b_G${head};${chunk}\x1b\\`);
+  }
+  return parts.join("");
+}
+
+/**
+ * Encode arbitrary image bytes (base64, any format iTerm2's host OS decodes —
+ * PNG/JPEG/GIF all included) as an OSC 1337 inline-image sequence. `inline=1`
+ * renders in place instead of downloading; `width`/`height` are given in CELLS
+ * (not "auto") so iTerm2's own scaling always agrees with jeo's precomputed
+ * {@link ImageFit} — the row-accounting in the caller depends on that agreement.
+ */
+export function encodeIterm2Image(base64Data: string, fit: ImageFit, name?: string): string {
+  const params = [`inline=1`, `width=${fit.columns}`, `height=${fit.rows}`, "preserveAspectRatio=1"];
+  if (name) params.push(`name=${Buffer.from(name).toString("base64")}`);
+  return `\x1b]1337;File=${params.join(";")}:${base64Data}\x07`;
+}
+
+/** True when `line` contains an inline-image escape sequence (Kitty APC or
+ *  iTerm2 OSC 1337) within its first 96 characters — a possible leading
+ *  `cursorUp(...)` prefix (see {@link renderInlineImage}) means the marker is not
+ *  always at offset 0. Callers that measure/truncate/wrap terminal lines by
+ *  DISPLAY WIDTH (`visibleWidth`, `truncateToWidth`, `wrapTextWithAnsi` in
+ *  `components/width.ts`) MUST treat a line matching this as opaque and pass it
+ *  through unchanged: the base64 payload is thousands of columns "wide" by a
+ *  naive count, and slicing mid-sequence corrupts or hangs the terminal (an
+ *  unterminated Kitty APC / OSC waits indefinitely for its `ESC \\` / BEL
+ *  terminator). Not currently wired into `width.ts` — every current image call
+ *  site (`insertAbove`) bypasses that pipeline entirely; exported so a future
+ *  call site can opt in without re-deriving the detection. */
+export function isImageEscapeLine(line: string): boolean {
+  const head = line.slice(0, 96);
+  return head.includes("\x1b_G") || head.includes("\x1b]1337;File=");
+}
+
+/** Human-readable stand-in for an attachment that can't be rendered inline
+ *  (unsupported terminal, unsupported format for the detected protocol, or an
+ *  undecodable dimension header). Mirrors the existing `⧉ N image(s) attached`
+ *  wording style used elsewhere in the TUI. */
+export function imageCaption(mediaType: string, dims: PixelDimensions | null, filename?: string): string {
+  const parts = [filename, `[${mediaType}]`, dims ? `${dims.widthPx}x${dims.heightPx}` : undefined].filter(Boolean);
+  return `⧉ ${parts.join(" ")}`;
+}
+
+export interface InlineImageResult {
+  /** Lines to feed into `Renderer.insertAbove` (or join with "\n" for a plain
+   *  `console.log`/pipe path). The array length equals the image's rendered
+   *  terminal-row footprint — every element is one physical row — so a caller
+   *  computing "rows written" from `lines.length` (as `insertAbove` does by
+   *  splitting on "\n") gets the correct height. */
+  lines: string[];
+  /** True when `lines` is a real inline image; false when it is a 1-line text
+   *  caption (unsupported terminal/format, or an unparsable header). */
+  rendered: boolean;
+}
+
+/**
+ * Build the escape sequence (or text caption) for one image attachment, sized to
+ * fit `maxColumns` x `maxRows` cells.
+ *
+ * Row bookkeeping (why this shape, not just "the sequence + rows-1 blank lines"):
+ * both protocols draw the image ANCHORED AT THE CURSOR'S ROW at the moment the
+ * escape is processed and expand DOWNWARD — they do not retroactively fill rows
+ * already scrolled past. So the cursor must already sit at the image's TOP row
+ * before the escape is written. `lines` therefore reserves `fit.rows - 1` blank
+ * rows FIRST (each later joined with "\n", which is what actually advances the
+ * cursor down — matches every other multi-row block `insertAbove` is fed), then a
+ * final row that rewinds the cursor back up to the reserved block's top
+ * (`cursorUp(fit.rows - 1)`) immediately before the escape sequence.
+ *
+ * After drawing, Kitty/kitty-compatible terminals leave the REAL cursor
+ * `fit.rows - 1` rows below the top (i.e. on the image's last row) — added to the
+ * caller's mandatory trailing "\n" (one per `InlineImageResult`, not emitted
+ * here), that lands the cursor exactly `fit.rows` rows below where it started,
+ * matching a plain `fit.rows`-line block of text. iTerm2 instead auto-advances
+ * PAST the image (`fit.rows` rows below the top), so a synthetic `cursorUp(1)`
+ * is appended after its escape to cancel that extra row and reach the same
+ * `fit.rows - 1` offset — keeping both protocols' net row math identical.
+ */
+export function renderInlineImage(
+  attachment: { mediaType: string; data: string },
+  protocol: ImageProtocol,
+  opts: { maxColumns: number; maxRows: number; filename?: string } = { maxColumns: 60, maxRows: 20 },
+): InlineImageResult {
+  const bytes = Buffer.from(attachment.data, "base64");
+  const dims = getImageDimensions(bytes, attachment.mediaType);
+  const caption = () => ({ lines: [imageCaption(attachment.mediaType, dims, opts.filename)], rendered: false });
+
+  if (protocol === ImageProtocol.None) return caption();
+  if (protocol === ImageProtocol.Kitty && attachment.mediaType !== "image/png") return caption(); // f=100 decodes PNG only
+  if (!dims) return caption(); // no protocol can size an image it can't measure
+
+  const cell = getCellPixelSize();
+  const fit = fitImageToCells(dims, opts.maxColumns, opts.maxRows, cell);
+  const seq =
+    protocol === ImageProtocol.Kitty
+      ? encodeKittyImage(attachment.data, fit)
+      : encodeIterm2Image(attachment.data, fit, opts.filename) + cursorUp(1); // cancel iTerm2's extra auto-advance row
+
+  const blankRows = Math.max(0, fit.rows - 1);
+  const lines = [...Array(blankRows).fill(""), cursorUp(blankRows) + seq];
+  return { lines, rendered: true };
+}