feat: move the terminal fully into the ssh-terminal plugin (B9)

plugins/ssh-terminal/tests/backend/images/image-storage-settings.test.ts

@@ -0,0 +1,191 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_IMAGE_HOST_PATH,
+  DEFAULT_IMAGE_MAX_BYTES,
+  DEFAULT_IMAGE_MAX_COUNT,
+  DEFAULT_IMAGE_TTL_MS,
+  defaultImageLocalDir,
+  parseImageHostPath,
+  parseImageLocalDir,
+  parseTerminalImageStorageMode,
+  resolveTerminalImageStorageSettings,
+  TERMINAL_IMAGE_STORAGE_KEYS,
+} from "../../../src/backend/images/image-storage-settings.js";
+import { createFakeContext } from "@termix/plugin-sdk/testing";
+import { readImageStorageSettings } from "../../../src/backend/settings.js";
+
+// parseImageLocalDir resolves against the host platform, so a POSIX literal
+// becomes a drive-rooted path on Windows. Compare against the same resolution.
+function localDir(posixPath: string): string {
+  return path.resolve(posixPath);
+}
+
+function stubSettings(values: Record<string, string> = {}) {
+  return {
+    get: async (key: string) => values[key] ?? null,
+  };
+}
+
+const EMPTY_ENV: NodeJS.ProcessEnv = {};
+
+describe("terminal image storage settings", () => {
+  describe("mode parsing", () => {
+    it("accepts the three documented modes case-insensitively", () => {
+      expect(parseTerminalImageStorageMode("auto")).toBe("auto");
+      expect(parseTerminalImageStorageMode("LOCAL")).toBe("local");
+      expect(parseTerminalImageStorageMode(" remote-sftp ")).toBe(
+        "remote-sftp",
+      );
+    });
+
+    it("rejects unknown modes and non-strings", () => {
+      expect(parseTerminalImageStorageMode("s3")).toBeNull();
+      expect(parseTerminalImageStorageMode("")).toBeNull();
+      expect(parseTerminalImageStorageMode(undefined)).toBeNull();
+    });
+  });
+
+  describe("path validation", () => {
+    it("accepts absolute local directories and normalizes them", () => {
+      expect(parseImageLocalDir("/var/lib/termix/images")).toBe(
+        localDir("/var/lib/termix/images"),
+      );
+      expect(parseImageLocalDir("/var/lib/termix/../termix/images")).toBeNull();
+    });
+
+    it("rejects relative, empty and NUL-containing local directories", () => {
+      expect(parseImageLocalDir("images")).toBeNull();
+      expect(parseImageLocalDir("./db/data/images")).toBeNull();
+      expect(parseImageLocalDir("")).toBeNull();
+      expect(parseImageLocalDir("/tmp/a\0b")).toBeNull();
+    });
+
+    it("requires the agent-visible host path to be POSIX-absolute", () => {
+      expect(parseImageHostPath("/tmp/termix-image-v0")).toBe(
+        "/tmp/termix-image-v0",
+      );
+      expect(parseImageHostPath("tmp/termix-image-v0")).toBeNull();
+      expect(parseImageHostPath("C:\\images")).toBeNull();
+      expect(parseImageHostPath("/tmp/a\0b")).toBeNull();
+    });
+  });
+
+  describe("resolution precedence", () => {
+    it("uses built-in defaults when neither the database nor env has values", async () => {
+      const resolved = await resolveTerminalImageStorageSettings(
+        stubSettings(),
+        EMPTY_ENV,
+      );
+      expect(resolved.mode).toBe("auto");
+      expect(resolved.localDir).toBe(defaultImageLocalDir(EMPTY_ENV));
+      expect(resolved.hostPath).toBe(DEFAULT_IMAGE_HOST_PATH);
+      expect(resolved.ttlMs).toBe(DEFAULT_IMAGE_TTL_MS);
+      expect(resolved.maxCount).toBe(DEFAULT_IMAGE_MAX_COUNT);
+      expect(resolved.maxBytes).toBe(DEFAULT_IMAGE_MAX_BYTES);
+    });
+
+    it("seeds defaults from legacy TERMIX_IMAGE_* env when no DB value exists", async () => {
+      const resolved = await resolveTerminalImageStorageSettings(
+        stubSettings(),
+        {
+          TERMIX_IMAGE_DIR: "/host-tmp/images",
+          TERMIX_IMAGE_HOST_PATH: "/tmp/images",
+          TERMIX_IMAGE_TTL_MS: "60000",
+          TERMIX_MAX_IMAGE_COUNT: "5",
+          TERMIX_MAX_IMAGE_STORAGE_BYTES: "10485760",
+        },
+      );
+      expect(resolved.localDir).toBe(localDir("/host-tmp/images"));
+      expect(resolved.hostPath).toBe("/tmp/images");
+      expect(resolved.ttlMs).toBe(60_000);
+      expect(resolved.maxCount).toBe(5);
+      expect(resolved.maxBytes).toBe(10_485_760);
+    });
+
+    it("lets persisted DB values win over legacy env values", async () => {
+      const resolved = await resolveTerminalImageStorageSettings(
+        stubSettings({
+          [TERMINAL_IMAGE_STORAGE_KEYS.localDir]: "/db/images",
+          [TERMINAL_IMAGE_STORAGE_KEYS.ttlMs]: "1000",
+          [TERMINAL_IMAGE_STORAGE_KEYS.maxCount]: "7",
+        }),
+        {
+          TERMIX_IMAGE_DIR: "/host-tmp/images",
+          TERMIX_IMAGE_TTL_MS: "60000",
+          TERMIX_MAX_IMAGE_COUNT: "5",
+        },
+      );
+      expect(resolved.localDir).toBe(localDir("/db/images"));
+      expect(resolved.ttlMs).toBe(1_000);
+      expect(resolved.maxCount).toBe(7);
+    });
+
+    it("falls through to env and defaults when the DB value is invalid", async () => {
+      const resolved = await resolveTerminalImageStorageSettings(
+        stubSettings({
+          [TERMINAL_IMAGE_STORAGE_KEYS.localDir]: "relative/path",
+          [TERMINAL_IMAGE_STORAGE_KEYS.ttlMs]: "not-a-number",
+        }),
+        { TERMIX_IMAGE_DIR: "/host-tmp/images" },
+      );
+      expect(resolved.localDir).toBe(localDir("/host-tmp/images"));
+      expect(resolved.ttlMs).toBe(DEFAULT_IMAGE_TTL_MS);
+    });
+
+    it("keeps legacy explicit local mappings on local mode", async () => {
+      const resolved = await resolveTerminalImageStorageSettings(
+        stubSettings(),
+        { TERMIX_IMAGE_DIR: "/host-tmp/images" },
+      );
+      expect(resolved.mode).toBe("local");
+      // hostPath falls back to the legacy local dir, which resolves natively.
+      expect(resolved.hostPath).toBe(localDir("/host-tmp/images"));
+      expect(resolved.localMappingConfigured).toBe(true);
+    });
+
+    it("lets a persisted DB mode override the legacy local mapping", async () => {
+      const resolved = await resolveTerminalImageStorageSettings(
+        stubSettings({
+          [TERMINAL_IMAGE_STORAGE_KEYS.mode]: "remote-sftp",
+        }),
+        { TERMIX_IMAGE_DIR: "/host-tmp/images" },
+      );
+      expect(resolved.mode).toBe("remote-sftp");
+    });
+
+    it("clamps out-of-range numeric values like the legacy env parsing did", async () => {
+      const resolved = await resolveTerminalImageStorageSettings(
+        stubSettings(),
+        {
+          TERMIX_IMAGE_TTL_MS: "-5",
+          TERMIX_MAX_IMAGE_COUNT: "0",
+          TERMIX_MAX_IMAGE_STORAGE_BYTES: "10",
+        },
+      );
+      expect(resolved.ttlMs).toBe(0);
+      expect(resolved.maxCount).toBe(1);
+      expect(resolved.maxBytes).toBe(1_048_576);
+    });
+
+    it("reads the plugin's admin settings, and treats unset fields as unset", async () => {
+      const { ctx } = createFakeContext({
+        settings: {
+          imageStorageMode: "local",
+          imageLocalDir: "/persisted/images",
+        },
+      });
+      const resolved = await readImageStorageSettings(ctx);
+      expect(resolved.mode).toBe("local");
+      expect(resolved.localDir).toBe(localDir("/persisted/images"));
+      // Nothing stored and no environment: the built-in default.
+      expect(resolved.maxCount).toBe(DEFAULT_IMAGE_MAX_COUNT);
+    });
+
+    it("keeps TERMINAL_IMAGE_STORAGE_KEYS as the lookup names", () => {
+      expect(TERMINAL_IMAGE_STORAGE_KEYS.mode).toBe(
+        "terminal_image_storage_mode",
+      );
+    });
+  });
+});

plugins/ssh-terminal/tests/backend/images/image-storage.test.ts

@@ -0,0 +1,571 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { EventEmitter } from "events";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+import { randomUUID } from "crypto";
+import {
+  REMOTE_IMAGE_DIR,
+  selectImageStorageMode,
+  storeImageLocally,
+  storeImageViaSftp,
+  TerminalImageStorageError,
+  type ImageSftpClient,
+} from "../../../src/backend/images/image-storage.js";
+import type { TerminalImageStorageSettings } from "../../../src/backend/images/image-storage-settings.js";
+
+const PNG_BYTES = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+
+function settings(
+  overrides: Partial<TerminalImageStorageSettings>,
+): TerminalImageStorageSettings {
+  return {
+    mode: "local",
+    localDir: "/nonexistent",
+    hostPath: "/tmp/termix-image-v0",
+    ttlMs: 3_600_000,
+    maxCount: 100,
+    maxBytes: 5_368_709_120,
+    localMappingConfigured: false,
+    ...overrides,
+  };
+}
+
+describe("selectImageStorageMode", () => {
+  it("keeps explicit modes deterministic regardless of capability", () => {
+    expect(
+      selectImageStorageMode(settings({ mode: "local" }), {
+        remoteSftpAvailable: true,
+      }),
+    ).toBe("local");
+    expect(
+      selectImageStorageMode(settings({ mode: "remote-sftp" }), {
+        remoteSftpAvailable: false,
+      }),
+    ).toBe("remote-sftp");
+  });
+
+  it("falls back on capability only in auto mode", () => {
+    expect(
+      selectImageStorageMode(settings({ mode: "auto" }), {
+        remoteSftpAvailable: true,
+      }),
+    ).toBe("remote-sftp");
+    expect(
+      selectImageStorageMode(settings({ mode: "auto" }), {
+        remoteSftpAvailable: false,
+      }),
+    ).toBe("unavailable");
+    expect(
+      selectImageStorageMode(
+        settings({ mode: "auto", localMappingConfigured: true }),
+        { remoteSftpAvailable: false, localHostVisible: true },
+      ),
+    ).toBe("local");
+  });
+});
+
+describe("storeImageLocally", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), "termix-images-test-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  async function seedFile(bytes: number, mtimeMs?: number): Promise<string> {
+    const name = `${randomUUID()}.png`;
+    const filePath = path.join(dir, name);
+    await fs.writeFile(filePath, Buffer.alloc(bytes));
+    if (mtimeMs !== undefined) {
+      const date = new Date(mtimeMs);
+      await fs.utimes(filePath, date, date);
+    }
+    return name;
+  }
+
+  it("writes a UUID-named PNG and returns the agent-visible host path", async () => {
+    const stored = await storeImageLocally(
+      PNG_BYTES,
+      settings({ localDir: dir, hostPath: "/host-view/images" }),
+    );
+
+    expect(stored.storage).toBe("local");
+    expect(stored.filename).toBe(`${stored.id}.png`);
+    expect(stored.shellPath).toBe(
+      path.posix.join("/host-view/images", stored.filename),
+    );
+    expect(stored.shellPath).not.toContain(dir);
+    await expect(fs.readFile(path.join(dir, stored.filename))).resolves.toEqual(
+      PNG_BYTES,
+    );
+  });
+
+  it("rejects with IMAGE_STORAGE_LIMIT_REACHED when the count cap is full", async () => {
+    await seedFile(10);
+    const error = await storeImageLocally(
+      PNG_BYTES,
+      settings({ localDir: dir, maxCount: 1 }),
+    ).catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_STORAGE_LIMIT_REACHED",
+    );
+  });
+
+  it("rejects with IMAGE_STORAGE_LIMIT_REACHED when the byte cap is full", async () => {
+    await seedFile(900);
+    const error = await storeImageLocally(
+      Buffer.alloc(200),
+      settings({ localDir: dir, maxBytes: 1_000 }),
+    ).catch((caught: unknown) => caught);
+
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_STORAGE_LIMIT_REACHED",
+    );
+  });
+
+  it("cleans expired files during upload so they no longer count", async () => {
+    await seedFile(10, Date.now() - 2 * 3_600_000);
+    const stored = await storeImageLocally(
+      PNG_BYTES,
+      settings({ localDir: dir, maxCount: 1, ttlMs: 3_600_000 }),
+    );
+
+    expect(stored.storage).toBe("local");
+    const remaining = await fs.readdir(dir);
+    expect(remaining).toEqual([stored.filename]);
+  });
+
+  it("fails closed when local storage inspection is unavailable", async () => {
+    const blocked = path.join(dir, "blocked-file");
+    await fs.writeFile(blocked, "not a directory");
+
+    const error = await storeImageLocally(
+      PNG_BYTES,
+      settings({ localDir: blocked }),
+    ).catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_LOCAL_INSPECTION_FAILED",
+    );
+  });
+  it("reports inspection failures before attempting a write", async () => {
+    const blocked = path.join(dir, "blocked");
+    await fs.writeFile(blocked, "not a directory");
+
+    const error = await storeImageLocally(
+      PNG_BYTES,
+      settings({ localDir: path.join(blocked, "images") }),
+    ).catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_LOCAL_INSPECTION_FAILED",
+    );
+  });
+});
+
+describe("storeImageViaSftp", () => {
+  function fakeSftp(behavior: {
+    mkdirError?: Error;
+    writeError?: Error;
+    stallWrite?: boolean;
+    stallLock?: boolean;
+    stallReaddir?: boolean;
+    stallRmdir?: boolean;
+    stallUnlink?: boolean;
+    readdirEntries?: Array<{ filename: string; mtime?: number; size?: number }>;
+    readdirError?: Error;
+    statMode?: number;
+  }): {
+    sftp: ImageSftpClient;
+    written: Map<string, Buffer>;
+    calls: {
+      mkdir: Array<{ dir: string; mode?: number }>;
+      createWriteStream: Array<{ path: string; mode?: number }>;
+    };
+    streams: Array<
+      NodeJS.WritableStream & { destroy: () => void; destroyed: boolean }
+    >;
+  } {
+    const written = new Map<string, Buffer>();
+    const streams: Array<
+      NodeJS.WritableStream & { destroy: () => void; destroyed: boolean }
+    > = [];
+    const calls = { mkdir: [], createWriteStream: [] } as {
+      mkdir: Array<{ dir: string; mode?: number }>;
+      createWriteStream: Array<{ path: string; mode?: number }>;
+    };
+    const sftp = {
+      mkdir: (
+        dir: string,
+        attrsOrCallback: { mode?: number } | ((err?: Error) => void),
+        maybeCallback?: (err?: Error) => void,
+      ) => {
+        const callback =
+          typeof attrsOrCallback === "function"
+            ? attrsOrCallback
+            : maybeCallback!;
+        calls.mkdir.push({
+          dir,
+          mode:
+            typeof attrsOrCallback === "function"
+              ? undefined
+              : attrsOrCallback.mode,
+        });
+        if (
+          behavior.stallLock &&
+          dir === `${REMOTE_IMAGE_DIR}/.termix-write-lock`
+        ) {
+          return;
+        }
+        callback(dir === REMOTE_IMAGE_DIR ? behavior.mkdirError : undefined);
+      },
+      stat: (
+        _dir: string,
+        callback: (error: Error | undefined, attrs?: { mode?: number }) => void,
+      ) => callback(undefined, { mode: behavior.statMode ?? 0o40700 }),
+      chmod: (_dir: string, _mode: number, callback: (error?: Error) => void) =>
+        callback(),
+      readdir: (
+        _dir: string,
+        callback: (
+          error: Error | undefined,
+          entries: Array<{
+            filename: string;
+            attrs?: { mtime?: number; size?: number };
+          }>,
+        ) => void,
+      ) => {
+        if (behavior.stallReaddir) return;
+        callback(
+          behavior.readdirError,
+          behavior.readdirEntries?.map((entry) => ({
+            filename: entry.filename,
+            attrs: entry,
+          })) ?? [],
+        );
+      },
+      createWriteStream: (remotePath: string, options?: { mode?: number }) => {
+        calls.createWriteStream.push({ path: remotePath, mode: options?.mode });
+        const stream = new EventEmitter() as NodeJS.WritableStream & {
+          end: (data: Buffer) => void;
+          destroy: () => void;
+          destroyed: boolean;
+        };
+        stream.destroyed = false;
+        stream.destroy = () => {
+          stream.destroyed = true;
+        };
+        streams.push(stream);
+        stream.end = (data: Buffer) => {
+          if (behavior.stallWrite) return;
+          queueMicrotask(() => {
+            if (behavior.writeError) {
+              stream.emit("error", behavior.writeError);
+              return;
+            }
+            written.set(remotePath, data);
+            stream.emit("close");
+          });
+        };
+        return stream;
+      },
+      unlink: (_remotePath: string, callback: (error?: Error) => void) => {
+        if (behavior.stallUnlink) return;
+        callback();
+      },
+      rmdir: (_dir: string, callback: (error?: Error) => void) => {
+        if (behavior.stallRmdir) return;
+        callback();
+      },
+    } as unknown as ImageSftpClient;
+    return { sftp, written, calls, streams };
+  }
+
+  it("writes into the remote image directory and returns its POSIX path", async () => {
+    const { sftp, written } = fakeSftp({});
+    const stored = await storeImageViaSftp(sftp, PNG_BYTES);
+
+    expect(stored.storage).toBe("remote-sftp");
+    expect(stored.shellPath).toBe(`${REMOTE_IMAGE_DIR}/${stored.id}.png`);
+    expect(written.get(stored.shellPath)).toEqual(PNG_BYTES);
+  });
+
+  it("requests restrictive modes for the remote directory and file", async () => {
+    const { sftp, calls } = fakeSftp({});
+    const stored = await storeImageViaSftp(sftp, PNG_BYTES);
+
+    expect(stored.storage).toBe("remote-sftp");
+    expect(calls.mkdir).toEqual([
+      { dir: REMOTE_IMAGE_DIR, mode: 0o700 },
+      { dir: `${REMOTE_IMAGE_DIR}/.termix-write-lock`, mode: 0o700 },
+    ]);
+    expect(calls.createWriteStream).toEqual([
+      { path: stored.shellPath, mode: 0o600 },
+    ]);
+  });
+  it("removes expired UUID PNGs with best-effort remote retention", async () => {
+    const nowMs = 10_000_000;
+    const expiredName = `${randomUUID()}.png`;
+    const freshName = `${randomUUID()}.png`;
+    const unlinked: string[] = [];
+    const base = fakeSftp({});
+    const sftp = base.sftp as ImageSftpClient & {
+      readdir: (
+        dir: string,
+        callback: (
+          err: Error | undefined,
+          entries: Array<{ filename: string; attrs?: { mtime?: number } }>,
+        ) => void,
+      ) => void;
+      unlink: (remotePath: string, callback: (err?: Error) => void) => void;
+    };
+    sftp.readdir = (_dir, callback) =>
+      callback(undefined, [
+        { filename: expiredName, attrs: { mtime: (nowMs - 7_200_000) / 1000 } },
+        { filename: freshName, attrs: { mtime: nowMs / 1000 } },
+        { filename: "other.txt", attrs: { mtime: 0 } },
+      ]);
+    sftp.unlink = (remotePath, callback) => {
+      unlinked.push(remotePath);
+      callback();
+    };
+
+    await storeImageViaSftp(sftp, PNG_BYTES, {
+      ttlMs: 3_600_000,
+      nowMs,
+    });
+
+    expect(unlinked).toEqual([`${REMOTE_IMAGE_DIR}/${expiredName}`]);
+  });
+  it("fails closed when remote quota inspection fails", async () => {
+    const { sftp } = fakeSftp({
+      readdirError: new Error("remote listing failed"),
+    });
+    const error = await storeImageViaSftp(sftp, PNG_BYTES, {
+      maxCount: 10,
+      maxBytes: 1024,
+    }).catch((caught: unknown) => caught);
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_REMOTE_QUOTA_UNAVAILABLE",
+    );
+  });
+
+  it("rejects remote writes at the configured count limit", async () => {
+    const { sftp } = fakeSftp({
+      readdirEntries: [{ filename: `${randomUUID()}.png`, size: 12 }],
+    });
+    const error = await storeImageViaSftp(sftp, PNG_BYTES, {
+      maxCount: 1,
+      maxBytes: 1024,
+    }).catch((caught: unknown) => caught);
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_STORAGE_LIMIT_REACHED",
+    );
+  });
+
+  it("destroys a stalled SFTP write after its timeout", async () => {
+    const { sftp, streams } = fakeSftp({ stallWrite: true });
+    const error = await storeImageViaSftp(sftp, PNG_BYTES, {
+      writeTimeoutMs: 25,
+    }).catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_REMOTE_WRITE_FAILED",
+    );
+    expect(streams[0]!.destroyed).toBe(true);
+  });
+  it("rejects an existing remote path that is not a directory", async () => {
+    const { sftp } = fakeSftp({
+      mkdirError: new Error("Failure: file already exists"),
+      statMode: 0o100644,
+    });
+    const error = await storeImageViaSftp(sftp, PNG_BYTES).catch(
+      (caught: unknown) => caught,
+    );
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_REMOTE_WRITE_FAILED",
+    );
+  });
+
+  it("preserves SFTP client context for directory inspection", async () => {
+    const base = fakeSftp({ mkdirError: new Error("already exists") });
+    const sftp = base.sftp;
+    sftp.lstat = function (
+      this: ImageSftpClient,
+      _dir: string,
+      callback: (error: Error | undefined, attrs?: { mode?: number }) => void,
+    ) {
+      if (this !== sftp) {
+        callback(new Error("SFTP context lost"));
+        return;
+      }
+      callback(undefined, { mode: 0o40700 });
+    };
+    const result = await storeImageViaSftp(sftp, PNG_BYTES);
+    expect(result.storage).toBe("remote-sftp");
+  });
+
+  it("tolerates mkdir failures for an already-existing directory", async () => {
+    const { sftp } = fakeSftp({
+      mkdirError: new Error("Failure: file already exists"),
+    });
+    await expect(storeImageViaSftp(sftp, PNG_BYTES)).resolves.toMatchObject({
+      storage: "remote-sftp",
+    });
+  });
+
+  it("cleans up a partially created remote file after a write failure", async () => {
+    const { sftp } = fakeSftp({ writeError: new Error("write failed") });
+    const unlinked: string[] = [];
+    (sftp as ImageSftpClient).unlink = (remotePath, callback) => {
+      unlinked.push(remotePath);
+      callback();
+    };
+
+    const error = await storeImageViaSftp(sftp, PNG_BYTES).catch(
+      (caught: unknown) => caught,
+    );
+
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect(unlinked).toHaveLength(1);
+    expect(unlinked[0]).toMatch(
+      new RegExp(`${REMOTE_IMAGE_DIR}/[0-9a-f-]+\\.png`),
+    );
+  });
+
+  it("preserves the write error when partial-file cleanup stalls", async () => {
+    const { sftp } = fakeSftp({
+      writeError: new Error("write failed"),
+      stallUnlink: true,
+    });
+    const error = await storeImageViaSftp(sftp, PNG_BYTES).catch(
+      (caught: unknown) => caught,
+    );
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_REMOTE_WRITE_FAILED",
+    );
+  }, 5_000);
+
+  it("recovers a stale remote lock before writing", async () => {
+    const base = fakeSftp({});
+    const sftp = base.sftp as ImageSftpClient;
+    const lockPath = `${REMOTE_IMAGE_DIR}/.termix-write-lock`;
+    let lockAttempt = 0;
+    const removed: string[] = [];
+    const originalMkdir = sftp.mkdir.bind(sftp);
+    sftp.mkdir = (dir, attrs, callback) => {
+      if (dir === lockPath && lockAttempt++ === 0) {
+        (typeof attrs === "function" ? attrs : callback!)(new Error("exists"));
+        return;
+      }
+      originalMkdir(dir, attrs, callback);
+    };
+    sftp.lstat = (_dir, callback) =>
+      callback(undefined, {
+        mode: 0o40700,
+        mtime: (Date.now() - 60_000) / 1000,
+      });
+    sftp.rmdir = (dir, callback) => {
+      removed.push(dir);
+      callback();
+    };
+
+    await expect(storeImageViaSftp(sftp, PNG_BYTES)).resolves.toMatchObject({
+      storage: "remote-sftp",
+    });
+    expect(removed).toContain(lockPath);
+  });
+
+  it("does not replace a successful write with an unlock failure", async () => {
+    const base = fakeSftp({});
+    const sftp = base.sftp as ImageSftpClient;
+    const lockPath = `${REMOTE_IMAGE_DIR}/.termix-write-lock`;
+    const originalMkdir = sftp.mkdir.bind(sftp);
+    sftp.mkdir = (dir, attrs, callback) => originalMkdir(dir, attrs, callback);
+    sftp.rmdir = (dir, callback) => {
+      if (dir === lockPath) callback(new Error("unlock failed"));
+      else callback();
+    };
+
+    const error = await storeImageViaSftp(sftp, PNG_BYTES).catch(
+      (caught: unknown) => caught,
+    );
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_REMOTE_WRITE_FAILED",
+    );
+  });
+
+  it("fails closed when remote lock acquisition stalls", async () => {
+    const { sftp } = fakeSftp({ stallLock: true });
+    const error = await storeImageViaSftp(sftp, PNG_BYTES).catch(
+      (caught: unknown) => caught,
+    );
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_REMOTE_WRITE_FAILED",
+    );
+  }, 12_000);
+
+  it("fails closed when remote quota inspection stalls", async () => {
+    const { sftp } = fakeSftp({ stallReaddir: true });
+    const error = await storeImageViaSftp(sftp, PNG_BYTES, {
+      maxCount: 10,
+      maxBytes: 1024,
+    }).catch((caught: unknown) => caught);
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_REMOTE_WRITE_FAILED",
+    );
+  }, 7_000);
+
+  it("fails closed when remote expiry cleanup stalls", async () => {
+    const { sftp } = fakeSftp({ stallReaddir: true });
+    const error = await storeImageViaSftp(sftp, PNG_BYTES, {
+      ttlMs: 1_000,
+    }).catch((caught: unknown) => caught);
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_REMOTE_WRITE_FAILED",
+    );
+  }, 7_000);
+
+  it("fails closed when remote lock release stalls", async () => {
+    const { sftp } = fakeSftp({ stallRmdir: true });
+    const error = await storeImageViaSftp(sftp, PNG_BYTES).catch(
+      (caught: unknown) => caught,
+    );
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_REMOTE_WRITE_FAILED",
+    );
+  }, 5_000);
+
+  it("maps SFTP failures to IMAGE_REMOTE_WRITE_FAILED", async () => {
+    const { sftp } = fakeSftp({ writeError: new Error("Permission denied") });
+    const error = await storeImageViaSftp(sftp, PNG_BYTES).catch(
+      (caught: unknown) => caught,
+    );
+
+    expect(error).toBeInstanceOf(TerminalImageStorageError);
+    expect((error as TerminalImageStorageError).code).toBe(
+      "IMAGE_REMOTE_WRITE_FAILED",
+    );
+    expect((error as TerminalImageStorageError).message).toBe(
+      "Failed to write image to the remote host",
+    );
+  });
+});

plugins/ssh-terminal/tests/backend/images/image-utils.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+import {
+  exceedsImageStorageLimit,
+  exceedsNormalizedImageSize,
+  imageExtensionForFormat,
+  createConcurrencyLimiter,
+  isExpiredImage,
+  isImageFilename,
+} from "../../../src/backend/images/image-utils.js";
+
+describe("terminal image utilities", () => {
+  it("accepts UUID-based image filenames", () => {
+    expect(isImageFilename("b797234d-eb5d-4b1b-b7f3-17c26f257506.jpeg")).toBe(
+      true,
+    );
+  });
+
+  it("rejects unsafe or unrelated filenames", () => {
+    expect(isImageFilename("../secrets.txt")).toBe(false);
+    expect(isImageFilename("not-an-image.jpeg")).toBe(false);
+    expect(isImageFilename("b797234d-eb5d-4b1b-b7f3-17c26f257506")).toBe(false);
+  });
+
+  it("maps decoded raster formats while excluding SVG", () => {
+    expect(imageExtensionForFormat("jpeg")).toBe("jpg");
+    expect(imageExtensionForFormat("heif")).toBe("heif");
+    expect(imageExtensionForFormat("tiff")).toBe("tiff");
+    expect(imageExtensionForFormat("svg")).toBeUndefined();
+    expect(imageExtensionForFormat(undefined)).toBeUndefined();
+  });
+
+  it("rejects normalized output beyond the byte ceiling", () => {
+    expect(exceedsNormalizedImageSize(10_000_001, 10_000_000)).toBe(true);
+    expect(exceedsNormalizedImageSize(10_000_000, 10_000_000)).toBe(false);
+  });
+  it("expires files older than the configured TTL", () => {
+    expect(isExpiredImage(1_000, 3_000, 1_000)).toBe(true);
+    expect(isExpiredImage(2_500, 3_000, 1_000)).toBe(false);
+  });
+
+  it("treats a zero TTL as retention disabled", () => {
+    expect(isExpiredImage(1_000, 999_999, 0)).toBe(false);
+  });
+
+  it("bounds the admission queue", async () => {
+    const limiter = createConcurrencyLimiter(1, 0);
+    const release = await limiter.acquire();
+    await expect(limiter.acquire()).rejects.toThrow("queue is full");
+    release();
+  });
+
+  it("rejects uploads that exceed the count or byte limit", () => {
+    expect(exceedsImageStorageLimit(100, 10, 1, 100, 1000)).toBe(true);
+    expect(exceedsImageStorageLimit(1, 900, 101, 100, 1000)).toBe(true);
+    expect(exceedsImageStorageLimit(1, 900, 100, 100, 1000)).toBe(false);
+  });
+
+  it("bounds concurrent work", async () => {
+    const limiter = createConcurrencyLimiter(1);
+    let active = 0;
+    let peak = 0;
+    const task = async () => {
+      const release = await limiter.acquire();
+      active += 1;
+      peak = Math.max(peak, active);
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      active -= 1;
+      release();
+    };
+
+    await Promise.all([task(), task(), task()]);
+
+    expect(peak).toBe(1);
+    expect(limiter.active).toBe(0);
+  });
+});