@hienlh/ppm 0.19.0 → 0.19.2

package/src/server/ws/terminal.ts

@@ -1,4 +1,5 @@
 import { statSync } from "node:fs";
+import { homedir } from "node:os";
 import { terminalService } from "../../services/terminal.service.ts";
 import { resolveProjectPath } from "../helpers/resolve-project.ts";
 import { assertAllowed, resolvePath } from "../../services/fs-path-guard.service.ts";
@@ -7,6 +8,9 @@ import { assertAllowed, resolvePath } from "../../services/fs-path-guard.service
  * Where a new shell starts. An explicit `cwd` (explorer "Open in Terminal") wins
  * over the project root and goes through the same allowlist as the filesystem
  * API, so a terminal cannot be spawned anywhere the explorer could not browse.
+ * Neither given (a project-less "run this command" — the remote-desktop
+ * checklist's `brew install ffmpeg` button) → the user's home, the same place the
+ * OS explorer starts browsing from.
  */
 function resolveStartDir(projectName: string | undefined, cwd: string | undefined): string {
   if (cwd) {
@@ -16,7 +20,7 @@ function resolveStartDir(projectName: string | undefined, cwd: string | undefine
     return resolved;
   }
   if (projectName) return resolveProjectPath(projectName);
-  throw new Error("Session not found");
+  return homedir();
 }
 
 /** Control message prefix for resize commands */
@@ -36,8 +40,10 @@ export const terminalWebSocket = {
 
     let session = id !== "new" ? terminalService.get(id) : undefined;
 
-    // If session doesn't exist and a start directory is known, create one
-    if (!session && (projectName || cwd)) {
+    // A fresh socket ("new") always gets a shell — project root, explicit cwd, or home — and
+    // so does a stale id that still knows its project/cwd (tab reopened after a restart).
+    // Only a stale id with no context left is "Session not found".
+    if (!session && (id === "new" || projectName || cwd)) {
       try {
         const startDir = resolveStartDir(projectName, cwd);
         // Create session with the requested ID — but TerminalService generates its own ID.

package/src/services/media-transcode/ffmpeg-capabilities.ts

@@ -2,9 +2,15 @@
  * Discover ffmpeg/ffprobe on this machine and pick the fastest working H.264 encoder.
  *
  * ffmpeg is an *optional* dependency: without it PPM still plays browser-native
- * media (mp4/webm) via Range requests, it just cannot transcode AVI/MKV. The
- * result is cached for the process lifetime — the binary does not appear
- * mid-session, and probing hardware encoders costs a real encode each.
+ * media (mp4/webm) via Range requests, it just cannot transcode AVI/MKV. A
+ * positive result is cached for the process lifetime — probing hardware encoders
+ * costs a real encode each. A *negative* result is not: the remote-desktop
+ * checklist tells the user to install ffmpeg and promises to notice, so "not
+ * found" is re-checked on every call (one `which` + a few `stat`s).
+ *
+ * `PATH` alone is not enough to find it. A daemon started by launchd inherits
+ * `/usr/bin:/bin:/usr/sbin:/sbin` — Homebrew's `/opt/homebrew/bin` is not on it —
+ * so the well-known install directories are probed after `Bun.which`.
  *
  * Hardware encoders are verified by encoding a few synthetic frames rather than by
  * grepping `ffmpeg -encoders`: the list only says the build was compiled with
@@ -60,11 +66,42 @@ async function encoderWorks(ffmpeg: string, encoder: string): Promise<boolean> {
   }
 }
 
+/** Where package managers put ffmpeg when it is not on the daemon's PATH. */
+function wellKnownBinDirs(): string[] {
+  switch (process.platform) {
+    case "darwin": return ["/opt/homebrew/bin", "/usr/local/bin", "/opt/local/bin"];
+    case "win32": {
+      const local = process.env.LOCALAPPDATA;
+      return [
+        ...(local ? [`${local}\\Microsoft\\WinGet\\Links`] : []),
+        "C:\\ProgramData\\chocolatey\\bin", "C:\\ffmpeg\\bin",
+      ];
+    }
+    default: return ["/usr/local/bin", "/usr/bin", "/snap/bin", `${process.env.HOME ?? ""}/.local/bin`];
+  }
+}
+
+/** `Bun.which` on `searchPath` (the process PATH by default) first, then the well-known
+ *  directories. Exported for tests. */
+export function findFfmpegBinary(
+  name: "ffmpeg" | "ffprobe",
+  dirs: string[] = wellKnownBinDirs(),
+  searchPath: string | undefined = process.env.PATH,
+): string | null {
+  const onPath = Bun.which(name, searchPath ? { PATH: searchPath } : undefined);
+  if (onPath) return onPath;
+  for (const dir of dirs) {
+    const found = Bun.which(name, { PATH: dir });
+    if (found) return found;
+  }
+  return null;
+}
+
 let cached: Promise<FfmpegCapabilities> | null = null;
 
 async function detect(): Promise<FfmpegCapabilities> {
-  const ffmpeg = Bun.which("ffmpeg");
-  const ffprobe = Bun.which("ffprobe");
+  const ffmpeg = findFfmpegBinary("ffmpeg");
+  const ffprobe = findFfmpegBinary("ffprobe");
   if (!ffmpeg) return { ffmpeg: null, ffprobe, encoder: null };
   for (const candidate of encoderCandidates()) {
     if (await encoderWorks(ffmpeg, candidate)) return { ffmpeg, ffprobe, encoder: candidate };
@@ -72,10 +109,14 @@ async function detect(): Promise<FfmpegCapabilities> {
   return { ffmpeg, ffprobe, encoder: null };
 }
 
-/** Cached capability lookup; the first call pays for the encoder probes. */
+/** Cached capability lookup; the first call that finds ffmpeg pays for the encoder probes.
+ *  "Not installed" is never cached — the user may be running `brew install ffmpeg` right now. */
 export function getFfmpegCapabilities(): Promise<FfmpegCapabilities> {
   if (!cached) {
-    cached = detect().catch((e) => {
+    cached = detect().then((caps) => {
+      if (!caps.ffmpeg) cached = null;
+      return caps;
+    }).catch((e) => {
       cached = null; // let a later call retry after an unexpected failure
       throw e;
     });

package/src/services/named-tunnel/named-tunnel-retry.ts

@@ -0,0 +1,26 @@
+/**
+ * Backoff schedule for re-attempting a named tunnel after it lost a spawn and
+ * the supervisor fell back to a quick URL.
+ *
+ * The fallback exists so a broken named setup never leaves the machine dark,
+ * but it used to be one-way: once quick was live, named was only retried on the
+ * next supervisor start or an explicit `retunnel`. That is wrong for a
+ * *transient* failure — observed live, a laptop waking from sleep spawns the
+ * connector before Wi-Fi is back, the 30s readiness wait expires, and the
+ * permanent hostname then serves 530 for hours even though the network
+ * recovered seconds later.
+ */
+
+/** 1min, 5min, 15min — then stop and leave the warning standing. */
+export const NAMED_RETRY_DELAYS_MS = [60_000, 300_000, 900_000] as const;
+
+/**
+ * Delay before retry number `attempt` (0-based), or null once the schedule is
+ * exhausted. Bounded on purpose: a genuinely broken setup (deleted tunnel,
+ * revoked token) must settle on quick with a visible warning rather than
+ * restart the connector forever.
+ */
+export function nextNamedRetryDelayMs(attempt: number): number | null {
+  if (!Number.isInteger(attempt) || attempt < 0) return null;
+  return NAMED_RETRY_DELAYS_MS[attempt] ?? null;
+}

package/src/services/named-tunnel/network-ready.ts

@@ -0,0 +1,63 @@
+/**
+ * "Is the network back yet?" gate for the named-tunnel spawn path.
+ *
+ * A connector started before the machine's Wi-Fi has reassociated cannot
+ * register, and the readiness wait then expires on a failure that would have
+ * cleared itself seconds later. Observed live after a laptop resumed from
+ * sleep: the supervisor regenerated the tunnel immediately, named timed out,
+ * and the permanent hostname served 530 until someone intervened.
+ *
+ * Only the named path waits: a quick tunnel that fails is retried with a fresh
+ * URL anyway, while a named failure costs the user their fixed address.
+ */
+
+/** Cheap, unauthenticated, and the exact host the connector needs anyway. */
+const PROBE_URL = "https://api.cloudflare.com/client/v4/";
+
+export interface NetworkReadyOptions {
+  /** Give up after this long and let the caller try regardless. */
+  timeoutMs?: number;
+  /** Wait between probes. */
+  intervalMs?: number;
+  /** Per-probe timeout. */
+  probeTimeoutMs?: number;
+  /** Injectable for tests; defaults to a HEAD against Cloudflare's API. */
+  probe?: () => Promise<boolean>;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}
+
+const defaultSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+async function defaultProbe(probeTimeoutMs: number): Promise<boolean> {
+  try {
+    // Any HTTP answer proves DNS + TCP + TLS to Cloudflare work; the status
+    // code is irrelevant (401/404 are just as good a signal as 200).
+    await fetch(PROBE_URL, { method: "HEAD", signal: AbortSignal.timeout(probeTimeoutMs) });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolves `true` as soon as Cloudflare is reachable, `false` if the budget
+ * runs out. Never throws: a failed wait is a hint, not a veto — the caller
+ * still attempts the spawn, because a probe can fail for reasons (proxy, DNS
+ * filtering) that would not stop the connector itself.
+ */
+export async function waitForCloudflareReachable(opts: NetworkReadyOptions = {}): Promise<boolean> {
+  const timeoutMs = opts.timeoutMs ?? 60_000;
+  const intervalMs = opts.intervalMs ?? 2_000;
+  const probeTimeoutMs = opts.probeTimeoutMs ?? 3_000;
+  const probe = opts.probe ?? (() => defaultProbe(probeTimeoutMs));
+  const sleep = opts.sleep ?? defaultSleep;
+  const now = opts.now ?? Date.now;
+
+  const deadline = now() + timeoutMs;
+  for (;;) {
+    if (await probe()) return true;
+    if (now() >= deadline) return false;
+    await sleep(intervalMs);
+  }
+}

package/src/services/supervisor.ts

@@ -22,6 +22,8 @@ import {
 import type { ResolvedTunnelConfig, TunnelMode } from "./named-tunnel/named-tunnel-config.ts";
 import { readTunnelConfigFresh, chooseTunnelSpawn } from "./named-tunnel/named-tunnel-runtime.ts";
 import { waitForLogLine } from "./named-tunnel/named-tunnel-readiness.ts";
+import { nextNamedRetryDelayMs } from "./named-tunnel/named-tunnel-retry.ts";
+import { waitForCloudflareReachable } from "./named-tunnel/network-ready.ts";
 import { decideNamedProbeAction, publicHostnameIsOurs } from "./named-tunnel/named-tunnel-probe-state.ts";
 import { isCloudflaredPid } from "./tunnel-registry.service.ts";
 import { getQuickTunnelArgs } from "./cloudflared.service.ts";
@@ -102,6 +104,18 @@ let namedTunnelMode: ResolvedTunnelConfig | null = null;
 // but live=quick, and every status write / throttle / restart decision must
 // key off what's actually running.
 let lastSpawnMode: TunnelMode = "quick";
+// How long to wait for the network before attempting a named tunnel.
+const NETWORK_WAIT_MS = 60_000;
+// Falling back to quick used to be permanent until the next supervisor start.
+// These drive a bounded set of retries so a transient failure (network not up
+// yet after a resume) heals itself instead of leaving the hostname dark.
+let namedRetryAttempt = 0;
+let namedRetryTimer: ReturnType<typeof setTimeout> | null = null;
+// A retry that finds the machine still offline re-arms the same rung instead
+// of burning it. Bounded so a laptop left off the network doesn't log a
+// deferral every minute for the rest of its uptime.
+let namedRetryDeferrals = 0;
+const MAX_NAMED_RETRY_DEFERRALS = 10;
 // Set once the named probe has already tried a restart-and-hope; a second
 // consecutive failure then warns and stops instead of looping kills forever.
 let namedProbeRestartAttempted = false;
@@ -293,6 +307,72 @@ async function ensureBindablePort(preferred: number, host: string): Promise<numb
  * The trycloudflare URL will change — unavoidable, the old quick-tunnel session
  * is dead. Fire-and-forget: spawnTunnel's own loop owns liveness afterwards.
  */
+/** Cancel a pending named retry — a newer decision supersedes it. */
+function cancelNamedRetry(): void {
+  if (namedRetryTimer) { clearTimeout(namedRetryTimer); namedRetryTimer = null; }
+}
+
+/**
+ * After a downgrade to quick, try named again on a bounded backoff.
+ *
+ * Re-checks everything at fire time rather than trusting the state captured
+ * when the timer was set: the user may have switched to quick deliberately, a
+ * `retunnel` may already have restored named, or the supervisor may be going
+ * down. Any of those makes the retry pointless or actively wrong.
+ */
+function scheduleNamedRetry(port: number): void {
+  cancelNamedRetry();
+  const delay = nextNamedRetryDelayMs(namedRetryAttempt);
+  if (delay === null) {
+    log("WARN", "Named tunnel still failing after the last retry — staying on the quick URL");
+    return;
+  }
+  const attemptNumber = namedRetryAttempt + 1;
+  log("INFO", `Named tunnel downgraded to quick — retrying in ${Math.round(delay / 1000)}s (#${attemptNumber})`);
+  namedRetryTimer = setTimeout(() => {
+    namedRetryTimer = null;
+    if (shuttingDown || getState() !== "running") return;
+    if (namedTunnelMode?.mode !== "named") return; // user switched to quick meanwhile
+    if (lastSpawnMode === "named") return;         // already recovered
+    // Restarting tears down the quick tunnel that is currently serving the
+    // machine, so only do it once the network can actually carry a connector —
+    // otherwise a still-offline laptop loses its working temporary URL too and
+    // gets a new one for nothing. Offline: re-arm the same rung, don't burn it.
+    void waitForCloudflareReachable({ timeoutMs: 5_000, intervalMs: 1_000 }).then((reachable) => {
+      if (shuttingDown || getState() !== "running") return;
+      if (namedTunnelMode?.mode !== "named" || lastSpawnMode === "named") return;
+      if (!reachable) {
+        if (++namedRetryDeferrals > MAX_NAMED_RETRY_DEFERRALS) {
+          log("WARN", "Named retry abandoned — network still down after repeated attempts");
+          return;
+        }
+        log("INFO", `Named retry #${attemptNumber} deferred — network still down`);
+        scheduleNamedRetry(port);
+        return;
+      }
+      namedRetryDeferrals = 0;
+      namedRetryAttempt = attemptNumber;
+      log("INFO", `Retrying the named tunnel (#${attemptNumber})`);
+      restartTunnel(port);
+    });
+  }, delay);
+  namedRetryTimer.unref?.();
+}
+
+/**
+ * Called once per successful spawn: arm the retry ladder when we had to fall
+ * back to quick, clear it the moment named is actually live again.
+ */
+function noteSpawnOutcomeForNamedRetry(mode: TunnelMode, downgraded: boolean, port: number): void {
+  if (mode === "named") {
+    cancelNamedRetry();
+    namedRetryAttempt = 0;
+    namedRetryDeferrals = 0;
+    return;
+  }
+  if (downgraded) scheduleNamedRetry(port);
+}
+
 function restartTunnel(port: number) {
   lastTunnelRegenAt = Date.now();
   if (tunnelChild) { try { tunnelChild.kill(); } catch {} tunnelChild = null; }
@@ -744,6 +824,15 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
   }
 
   const attempts = buildTunnelAttempts(namedTunnelMode, port);
+  // Only the named path pays for this: its failure costs the user their fixed
+  // address, while a quick tunnel just retries with a new URL. Spawning a
+  // connector before the machine's network is back is the difference between
+  // "reconnects in 5s" and "hostname dark until someone notices".
+  if (attempts[0]?.mode === "named") {
+    const reachable = await waitForCloudflareReachable({ timeoutMs: NETWORK_WAIT_MS });
+    if (!reachable) log("WARN", `Cloudflare unreachable after ${NETWORK_WAIT_MS / 1000}s — attempting the tunnel anyway`);
+    if (generation !== tunnelGeneration) return; // superseded while waiting
+  }
   const logPath = cloudflaredLogPath();
   // Truncate stale content from a prior generation; best-effort — Windows can
   // silently fail this while a previous detached cloudflared still holds the
@@ -821,6 +910,7 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
     adoptedTunnelPid = winPid;
     tunnelChild = null;
     lastSpawnMode = successfulMode;
+    noteSpawnOutcomeForNamedRetry(successfulMode, downgraded, port);
     // `namedProbeRestartAttempted` is deliberately NOT touched here — see the
     // probe's `decideNamedProbeAction` state machine. A successful spawn only
     // proves cloudflared reconnected to Cloudflare's edge, not that the
@@ -908,6 +998,7 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
   }
 
   lastSpawnMode = successfulMode;
+  noteSpawnOutcomeForNamedRetry(successfulMode, downgraded, port);
   // `namedProbeRestartAttempted` is deliberately NOT touched here — see the
   // probe's `decideNamedProbeAction` state machine and the win32 branch above
   // for why a bare spawn success must never re-arm the one-restart budget.
@@ -1708,6 +1799,7 @@ export async function softStop() {
 export function shutdown() {
   if (shuttingDown) return;
   shuttingDown = true;
+  cancelNamedRetry();
   log("INFO", "Supervisor shutting down");
 
   // Unblock if paused
@@ -1910,6 +2002,10 @@ export async function runSupervisor(opts: {
         // over from the outage trips "restart once" after a handful of probes.
         namedProbeRestartAttempted = false;
         tunnelFailCount = 0;
+        // A deliberate retunnel supersedes any pending automatic retry, and
+        // restarts the ladder so a later transient failure gets a full budget.
+        cancelNamedRetry();
+        namedRetryAttempt = 0;
         restartTunnel(_opts.port);
         // Deliberate fall-through (no return): a bare `ppm restart` sends a
         // bare SIGUSR2 with no command file of its own, and a `retunnel` that
@@ -2059,6 +2155,8 @@ export async function runSupervisor(opts: {
           // rather than inheriting a stale exhausted one (flag AND counter).
           namedProbeRestartAttempted = false;
           tunnelFailCount = 0;
+          cancelNamedRetry();
+          namedRetryAttempt = 0;
           restartTunnel(_opts.port);
         });
       }

package/src/services/transcript-images.ts

@@ -1,5 +1,6 @@
 import { readImageDimensions } from "./image-dimensions.ts";
 import { base64ByteLength, imagePlaceholderText } from "../shared/tool-result-content.ts";
+import { MAX_IMAGE_DIMENSION } from "../shared/image-limits.ts";
 
 /**
  * Auditing and removal of image payloads inside a Claude Code session transcript.
@@ -11,9 +12,14 @@ import { base64ByteLength, imagePlaceholderText } from "../shared/tool-result-co
  *
  * Images live in two places, and they are not equally safe to remove. A tool result can be
  * produced again by re-reading the file it came from, so those are removed by default. An
- * image the user attached to a message usually exists nowhere else, so it is left alone
- * unless the caller opts in — which it must be able to do, because a single oversized
- * attachment is enough to make every later turn of the session fail outright.
+ * attachment is left alone unless the caller opts in.
+ *
+ * That default is now more cautious than it needs to be for images this app sent itself: the
+ * composer uploads a copy before embedding the payload, and leaves the path in the message, so
+ * such an attachment is as re-readable as a tool result. It stays opt-in because a transcript
+ * also collects attachments from elsewhere — another client, an older build, a session shared
+ * with the CLI — and for those the payload really is the last copy. The caller must be able to
+ * reach it either way: one oversized attachment fails every later turn of the session.
  *
  * A tool result's payload sits at `message.content[].content[]`; an attachment sits directly
  * at `message.content[]`. A record also carries an image-shaped echo at the top-level
@@ -28,7 +34,7 @@ import { base64ByteLength, imagePlaceholderText } from "../shared/tool-result-co
  * Comparisons here are `>=` rather than `>` for that reason: treating 2000px as acceptable
  * hides the one image the API is rejecting and makes a cleanup look like a no-op.
  */
-export const MANY_IMAGE_DIMENSION_LIMIT = 2000;
+export const MANY_IMAGE_DIMENSION_LIMIT = MAX_IMAGE_DIMENSION;
 
 /** Base64 characters decoded to inspect a header — a JPEG frame can sit behind EXIF. */
 const HEADER_CHARS = 4096;
@@ -38,9 +44,10 @@ export type StripMode = "oversized" | "all";
 /** Which of the two image locations a scan or strip should cover. */
 export interface ImageScopeOpts {
   /**
-   * Also cover images the user attached to their own messages. Off by default: the payload
-   * in the transcript is typically the only remaining copy, so removing it is lossy in a way
-   * removing a tool result is not.
+   * Also cover images the user attached to their own messages. Off by default, because a
+   * transcript may hold attachments this app never uploaded — from another client or an older
+   * build — for which the embedded payload is the last copy. Attachments the composer sent
+   * keep an uploaded file and its path, so removing those is recoverable.
    */
   includeAttachments?: boolean;
 }

package/src/services/upgrade.service.ts

@@ -117,10 +117,15 @@ let upgradeInProgress = false;
 
 /** Build the global-install command. Absolute runtime path (not a bare
  *  "bun"/"npm") because autostart (launchd/systemd) may not have the runtime's
- *  bin dir on $PATH, where a bare name fails with "Executable not found". */
+ *  bin dir on $PATH, where a bare name fails with "Executable not found".
+ *
+ *  bun gets `--no-cache`: it resolves versions from a cached package manifest
+ *  and, right after a release, that manifest predates the version the update
+ *  check just found — `bun install -g pkg@new` then fails with "No version
+ *  matching … (but package exists)" until the cache happens to expire. */
 export function buildUpgradeCommand(method: "bun" | "npm", pkg: string): string[] {
   return method === "bun"
-    ? [process.execPath, "install", "-g", pkg]
+    ? [process.execPath, "install", "-g", "--no-cache", pkg]
     : [resolveNpmBin(), "install", "-g", pkg];
 }
 

package/src/shared/image-limits.ts

@@ -0,0 +1,37 @@
+/**
+ * The per-image dimension ceiling the API applies, and the arithmetic for staying under it.
+ *
+ * Shared because both ends of the pipeline need the same number: the browser downscales an
+ * attachment before it is ever uploaded, and the transcript tooling reports on images that
+ * slipped in from elsewhere (another client, an older build) still carrying the full size.
+ */
+
+/**
+ * Longest side, in pixels, at which the API starts refusing an image once a request carries
+ * several of them. The value is a ceiling, so an image measuring exactly this is already over
+ * it — comparisons are `>=`, and a downscale targets strictly below.
+ */
+export const MAX_IMAGE_DIMENSION = 2000;
+
+/**
+ * Dimensions that bring an image under the cap, or null when it is already small enough.
+ *
+ * Scales the longest side to one pixel below the cap and takes the other side with it, so the
+ * aspect ratio survives and the result cannot land back on the boundary through rounding.
+ */
+export function fitWithin(
+  width: number,
+  height: number,
+  max: number = MAX_IMAGE_DIMENSION,
+): { width: number; height: number } | null {
+  if (!(width > 0) || !(height > 0)) return null;
+  const longest = Math.max(width, height);
+  if (longest < max) return null;
+
+  const target = max - 1;
+  const scale = target / longest;
+  return {
+    width: width >= height ? target : Math.max(1, Math.round(width * scale)),
+    height: height > width ? target : Math.max(1, Math.round(height * scale)),
+  };
+}

package/src/types/api.ts

@@ -23,7 +23,9 @@ export type TerminalWsMessage =
 
 /** WebSocket message types (chat) */
 export type ChatWsClientMessage =
-  | { type: "message"; content: string; permissionMode?: string; priority?: 'now' | 'next' | 'later'; images?: Array<{ data: string; mediaType: string }>; model?: string; effort?: string; thinking?: boolean }
+  | { type: "message"; content: string; permissionMode?: string; priority?: 'now' | 'next' | 'later'; images?: Array<{ data: string; mediaType: string }>;
+  /** Uploaded paths for the same images, for providers that take a file not a payload. */
+  imagePaths?: string[]; model?: string; effort?: string; thinking?: boolean }
   | { type: "cancel" }
   | { type: "set_model"; model: string }
   | { type: "set_effort"; effort: string }

package/src/types/chat.ts

@@ -2,6 +2,12 @@ export interface SendMessageOpts {
   permissionMode?: import("./config").PermissionMode | string;
   priority?: 'now' | 'next' | 'later';
   images?: Array<{ data: string; mediaType: string }>;
+  /**
+   * Uploaded paths for the same attachments, for providers that take a file rather than a
+   * payload. Codex's turn input accepts `localImage` by path and has no base64 form, so an
+   * image reaches it this way or not at all.
+   */
+  imagePaths?: string[];
   /** Per-session model override; falls back to provider config model when absent */
   model?: string;
   /** Override the provider's 1M-context setting for this call (false = never add the

package/src/types/extension-messages.ts

@@ -22,6 +22,8 @@ export interface TreeItemMsg {
   description?: string;
   tooltip?: string;
   icon?: string;
+  /** Label wraps instead of truncating — for rows whose text is the content. */
+  wrap?: boolean;
   collapsibleState: "none" | "collapsed" | "expanded";
   command?: string;
   children?: TreeItemMsg[];

package/src/web/components/chat/attachment-chips.tsx

@@ -52,6 +52,16 @@ export function AttachmentChips({ attachments, onRemove }: AttachmentChipsProps)
               <Loader2 className="size-3 shrink-0 animate-spin text-text-subtle" />
             ) : att.status === "error" ? (
               <span className="text-error shrink-0" title="Upload failed">!</span>
+            ) : att.resized ? (
+              // Says what happened to the image. A screenshot arriving at the model smaller
+              // than the one that was pasted is worth stating rather than leaving to be
+              // discovered, and the measurement was already being recorded for nothing.
+              <span
+                className="shrink-0 text-[10px] text-text-subtle"
+                title={`Shrunk from ${att.resized.from.width}x${att.resized.from.height} to ${att.resized.to.width}x${att.resized.to.height}`}
+              >
+                {att.resized.to.width}&times;{att.resized.to.height}
+              </span>
             ) : null}
 
             {/* Remove button */}

package/src/web/components/chat/chat-tab.tsx

@@ -2,6 +2,8 @@ import { useState, useCallback, useRef, useEffect } from "react";
 import { Loader2, Upload, X } from "lucide-react";
 import { toast } from "sonner";
 import { api, projectUrl } from "@/lib/api-client";
+import { selectInlineImages } from "@/lib/image-resize-limits";
+import { splitAttachmentMarkers } from "@/lib/attachment-marker-split";
 import { useChat } from "@/hooks/use-chat";
 import { useUsage } from "@/hooks/use-usage";
 import { useTabStore } from "@/stores/tab-store";
@@ -56,7 +58,7 @@ export function ChatTab({ metadata, tabId }: ChatTabProps) {
   );
 
   // Pending message to send after WS connects (replaces unreliable setTimeout)
-  const pendingSendRef = useRef<{ content: string; permissionMode?: string } | null>(null);
+  const pendingSendRef = useRef<{ content: string; permissionMode?: string; images?: Array<{ data: string; mediaType: string }>; imagePaths?: string[] } | null>(null);
 
   // Drag-and-drop state
   const [isDragging, setIsDragging] = useState(false);
@@ -142,9 +144,9 @@ export function ChatTab({ metadata, tabId }: ChatTabProps) {
   // Flush pending message once WS connects (replaces unreliable setTimeout)
   useEffect(() => {
     if (isConnected && pendingSendRef.current) {
-      const { content, permissionMode: pm } = pendingSendRef.current;
+      const { content, permissionMode: pm, images: pendingImages, imagePaths: pendingPaths } = pendingSendRef.current;
       pendingSendRef.current = null;
-      sendMessage(content, { permissionMode: pm });
+      sendMessage(content, { permissionMode: pm, ...(pendingImages?.length && { images: pendingImages }), ...(pendingPaths?.length && { imagePaths: pendingPaths }) });
     }
   }, [isConnected, sendMessage]);
 
@@ -350,7 +352,11 @@ export function ChatTab({ metadata, tabId }: ChatTabProps) {
 
   /** Build message content with file references and inline text snippets prepended */
   const buildMessageWithAttachments = useCallback(
-    (content: string, attachments: ChatAttachment[]): string => {
+    (
+      content: string,
+      attachments: ChatAttachment[],
+      inlineImages: Array<{ data: string; mediaType: string }> = [],
+    ): string => {
       if (attachments.length === 0) return content;
 
       const parts: string[] = [];
@@ -360,12 +366,27 @@ export function ChatTab({ metadata, tabId }: ChatTabProps) {
         if (att.textContent) parts.push(att.textContent);
       }
 
-      // Server-uploaded file references
-      const fileAtts = attachments.filter((a) => a.serverPath);
-      if (fileAtts.length > 0) {
-        const fileRefs = fileAtts.map((a) => a.serverPath!).join("\n");
+      // Server-uploaded file references. An image keeps its path even when the payload rides
+      // along with the message, because the transcript is what the chat re-renders from and
+      // the path is the only thing in it a thumbnail can be drawn from.
+      //
+      // An image sent inline says so in the marker. A bare path in a user message reads as an
+      // invitation to open it, and a model that takes it pays for the same picture twice —
+      // once inline, once as a tool result, both replayed on every later turn.
+      //
+      // Which marker an image gets follows the payloads that are actually going out, not
+      // `imageData` alone: the per-message caps can leave one behind, and announcing that its
+      // contents are included would hand the model neither the picture nor a reason to open
+      // the file. `inlineImages` defaults to none, so a caller that sends no payloads at all
+      // (the edit-fork path takes only text) gets the plain markers throughout.
+      const { inlineImagePaths, pathOnlyPaths } = splitAttachmentMarkers(attachments, inlineImages);
+      for (const path of inlineImagePaths) {
+        parts.push(`[Attached image (contents included in this message): ${path}]`);
+      }
+      if (pathOnlyPaths.length > 0) {
+        const fileRefs = pathOnlyPaths.join("\n");
         parts.push(
-          fileAtts.length === 1
+          pathOnlyPaths.length === 1
             ? `[Attached file: ${fileRefs}]`
             : `[Attached files:\n${fileRefs}\n]`,
         );
@@ -379,8 +400,11 @@ export function ChatTab({ metadata, tabId }: ChatTabProps) {
 
   const handleSend = useCallback(
     async (content: string, attachments: ChatAttachment[] = [], priority?: MessagePriority) => {
-      const fullContent = buildMessageWithAttachments(content, attachments);
-      if (!fullContent.trim()) return;
+      const images = selectInlineImages(attachments);
+      const fullContent = buildMessageWithAttachments(content, attachments, images);
+      // Providers that take a file rather than a payload (codex) read these instead.
+      const imagePaths = attachments.filter((a) => a.isImage && a.serverPath).map((a) => a.serverPath!);
+      if (!fullContent.trim() && images.length === 0) return;
 
       if (!sessionId) {
         try {
@@ -394,14 +418,14 @@ export function ChatTab({ metadata, tabId }: ChatTabProps) {
           setSessionId(session.id);
           setProviderId(session.providerId);
           // Queue message — will be sent by effect when WS reports isConnected
-          pendingSendRef.current = { content: fullContent, permissionMode };
+          pendingSendRef.current = { content: fullContent, permissionMode, images, imagePaths };
           return;
         } catch (e) {
           console.error("Failed to create session:", e);
           return;
         }
       }
-      sendMessage(fullContent, { permissionMode, priority });
+      sendMessage(fullContent, { permissionMode, priority, ...(images.length > 0 && { images }), ...(imagePaths.length > 0 && { imagePaths }) });
     },
     [sessionId, providerId, projectName, sendMessage, buildMessageWithAttachments, permissionMode, metadata],
   );