@remodex/rmx 1.0.2

package/src/adapters/run-turn-queue.ts

@@ -0,0 +1,114 @@
+import type { AdapterEvent } from "../types";
+
+type QueueReader = (result: IteratorResult<AdapterEvent>) => void;
+
+export const PREFLIGHT_HEARTBEAT_RETAIN_LIMIT = 16;
+
+export interface AdapterEventQueue {
+  push(event: AdapterEvent): void;
+  close(): void;
+  stream(): AsyncIterable<AdapterEvent>;
+  collect(): Promise<AdapterEvent[]>;
+}
+
+export interface AdapterEventPreflight {
+  stream: AsyncIterable<AdapterEvent>;
+  error?: Extract<AdapterEvent, { type: "error" }>;
+  empty: boolean;
+}
+
+async function* replay(
+  buffered: readonly AdapterEvent[],
+  iterator: AsyncIterator<AdapterEvent>,
+): AsyncGenerator<AdapterEvent> {
+  try {
+    for (const event of buffered) yield event;
+    while (true) {
+      const next = await iterator.next();
+      if (next.done) return;
+      yield next.value;
+    }
+  } finally {
+    await iterator.return?.();
+  }
+}
+
+export async function preflightAdapterEvents(
+  source: AsyncIterable<AdapterEvent>,
+): Promise<AdapterEventPreflight> {
+  const iterator = source[Symbol.asyncIterator]();
+  const buffered: AdapterEvent[] = [];
+  while (true) {
+    const next = await iterator.next();
+    if (next.done) return { stream: replay(buffered, iterator), empty: true };
+    if (next.value.type === "heartbeat") {
+      buffered.push(next.value);
+      if (buffered.length > PREFLIGHT_HEARTBEAT_RETAIN_LIMIT) buffered.shift();
+      continue;
+    }
+    buffered.push(next.value);
+    if (next.value.type === "error") {
+      await iterator.return?.();
+      return { stream: replay(buffered, iterator), error: next.value, empty: false };
+    }
+    return { stream: replay(buffered, iterator), empty: false };
+  }
+}
+
+export function createAdapterEventQueue(opts?: {
+  maxBacklog?: number;
+  onBacklogExceeded?: () => void;
+}): AdapterEventQueue {
+  const queued: AdapterEvent[] = [];
+  const readers: QueueReader[] = [];
+  const maxBacklog = opts?.maxBacklog ?? 1_024;
+  let closed = false;
+
+  const push = (event: AdapterEvent): void => {
+    if (closed) return;
+    const reader = readers.shift();
+    if (reader) {
+      reader({ done: false, value: event });
+      return;
+    }
+    if (queued.length >= maxBacklog) {
+      opts?.onBacklogExceeded?.();
+      queued.push({ type: "error", message: "consumer backlog exceeded — turn aborted" });
+      close();
+      return;
+    }
+    queued.push(event);
+  };
+
+  const close = (): void => {
+    if (closed) return;
+    closed = true;
+    while (readers.length > 0) {
+      readers.shift()?.({ done: true, value: undefined as never });
+    }
+  };
+
+  async function* stream(): AsyncIterable<AdapterEvent> {
+    while (true) {
+      const next = queued.shift();
+      if (next) {
+        yield next;
+        continue;
+      }
+      if (closed) return;
+      const result = await new Promise<IteratorResult<AdapterEvent>>(resolve => {
+        readers.push(resolve);
+      });
+      if (result.done) return;
+      yield result.value;
+    }
+  }
+
+  const collect = async (): Promise<AdapterEvent[]> => {
+    const events: AdapterEvent[] = [];
+    for await (const event of stream()) events.push(event);
+    return events;
+  };
+
+  return { push, close, stream, collect };
+}

package/src/adapters/tool-catalog-nudge.ts

@@ -0,0 +1,71 @@
+import {
+  isAllowedToolChoice,
+  namespacedToolName,
+  toolAllowedByChoice,
+  toolChoiceAliases,
+  type OcxRequestOptions,
+  type OcxTool,
+  type OcxProviderConfig,
+} from "../types";
+
+const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS", "apply_patch"] as const;
+
+function quoteNames(names: readonly string[]): string {
+  return names.map(name => `\`${name}\``).join(", ");
+}
+
+function uniqueNames(names: readonly string[]): string[] {
+  return [...new Set(names.filter(name => name.trim().length > 0))];
+}
+
+function toolChoiceAllows(tool: Pick<OcxTool, "namespace" | "name">, toolChoice: OcxRequestOptions["toolChoice"] | undefined): boolean {
+  if (!toolChoice || toolChoice === "auto" || toolChoice === "required") return true;
+  if (toolChoice === "none") return false;
+  if (isAllowedToolChoice(toolChoice)) return toolAllowedByChoice(tool, new Set(toolChoice.allowedTools));
+  return toolChoiceAliases(tool).includes(toolChoice.name);
+}
+
+function isOpenAIOrChatGPTHost(hostname: string): boolean {
+  return hostname === "openai.com"
+    || hostname.endsWith(".openai.com")
+    || hostname === "chatgpt.com"
+    || hostname.endsWith(".chatgpt.com");
+}
+
+export function shouldInjectNonOpenAIToolCatalogNudge(provider: Pick<OcxProviderConfig, "baseUrl">): boolean {
+  try {
+    return !isOpenAIOrChatGPTHost(new URL(provider.baseUrl).hostname);
+  } catch {
+    return true;
+  }
+}
+
+export function buildNonOpenAIToolCatalogNudgeFromNames(wireNames: readonly string[] | undefined): string | undefined {
+  const names = uniqueNames(wireNames ?? []);
+  if (names.length === 0) return undefined;
+
+  const advertised = new Set(names);
+  const unavailableNeighborNames = NEIGHBOR_AGENT_TOOL_NAMES.filter(name => !advertised.has(name));
+
+  return [
+    "Tool contract: use the current tool catalog as ground truth.",
+    `Valid tool names for this turn are exactly ${quoteNames(names)}.`,
+    "Call only listed names with their listed argument keys; do not invent, translate, or rename tools.",
+    unavailableNeighborNames.length > 0
+      ? `Do not use neighboring-agent tool names ${quoteNames(unavailableNeighborNames)} unless this turn's catalog lists those exact names.`
+      : undefined,
+    "If you need shell, file search, file read, edit, or discovery behavior, choose the listed tool that provides that capability.",
+    "Count a tool call only after its tool result returns; batch independent read-only calls when the runtime supports it.",
+  ].filter((line): line is string => typeof line === "string").join(" ");
+}
+
+export function buildNonOpenAIToolCatalogNudgeForTools(
+  tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
+  toolChoice?: OcxRequestOptions["toolChoice"],
+  toWireName: (tool: Pick<OcxTool, "namespace" | "name">) => string = tool => namespacedToolName(tool.namespace, tool.name),
+): string | undefined {
+  const visibleNames = tools
+    ?.filter(tool => toolChoiceAllows(tool, toolChoice))
+    .map(toWireName);
+  return buildNonOpenAIToolCatalogNudgeFromNames(visibleNames);
+}

package/src/adapters/upstream-http-error.ts

@@ -0,0 +1,48 @@
+import { readBoundedResponseBody } from "../lib/bounded-body";
+import { redactSecretString } from "../lib/redact";
+
+const ABSOLUTE_PATH_PATTERN = /(?:\/Users\/[^ "';,]+|\/home\/[^ "';,]+|\/root\/[^ "';,]*|[A-Za-z]:\\Users\\[^ "';,]+)/g;
+
+export function sanitizeUpstreamErrorText(value: string): string {
+  return redactSecretString(value).replace(ABSOLUTE_PATH_PATTERN, "[REDACTED_PATH]");
+}
+
+export function safeUpstreamErrorString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+export function parseUpstreamJsonPayload(payloadText: string): unknown | undefined {
+  const trimmed = payloadText.trim();
+  if (!trimmed || (!trimmed.startsWith("{") && !trimmed.startsWith("["))) return undefined;
+  try {
+    return JSON.parse(trimmed) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function readDisplaySafeErrorPayloadText(res: Response, signal?: AbortSignal): Promise<string> {
+  try {
+    const body = await readBoundedResponseBody(res, { signal });
+    return body.displaySafe ? body.text : "";
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    return "";
+  }
+}
+
+export async function normalizeUpstreamHttpErrorResponse(
+  res: Response,
+  opts: { signal?: AbortSignal; formatMessage: (payloadText: string) => string | Promise<string> },
+): Promise<Response> {
+  if (res.ok) return res;
+  const payloadText = await readDisplaySafeErrorPayloadText(res, opts.signal);
+  const headers = new Headers(res.headers);
+  headers.delete("content-encoding");
+  headers.delete("content-length");
+  return new Response(await opts.formatMessage(payloadText), {
+    status: res.status,
+    statusText: res.statusText,
+    headers,
+  });
+}

package/src/android-remote/assets.ts

@@ -0,0 +1,218 @@
+import { Buffer } from "node:buffer";
+import { randomBytes } from "node:crypto";
+import { open, realpath, stat } from "node:fs/promises";
+import {
+  basename,
+  isAbsolute,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
+
+const ANDROID_ASSET_TTL_MS = 60 * 60 * 1_000;
+const ANDROID_ASSET_MAX_BYTES = 40 * 1024 * 1024;
+const ANDROID_ASSET_MAX_TICKETS = 512;
+const ANDROID_ASSET_ROUTE_PREFIX = "/api/android-remote/assets/";
+
+type AndroidImageAsset = {
+  readonly path: string;
+  readonly mimeType: string;
+  readonly size: number;
+  readonly expiresAt: number;
+};
+
+function comparablePath(value: string): string {
+  return process.platform === "win32" ? value.toLowerCase() : value;
+}
+
+function pathIsWithinRoot(root: string, candidate: string): boolean {
+  const child = relative(comparablePath(root), comparablePath(candidate));
+  return child !== ".."
+    && !child.startsWith(`..${sep}`)
+    && !isAbsolute(child);
+}
+
+async function imageMimeType(path: string): Promise<string | null> {
+  const handle = await open(path, "r");
+  try {
+    const bytes = Buffer.alloc(16);
+    const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+    const header = bytes.subarray(0, bytesRead);
+    if (
+      header.length >= 8
+      && header.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+    ) return "image/png";
+    if (
+      header.length >= 3
+      && header[0] === 0xff
+      && header[1] === 0xd8
+      && header[2] === 0xff
+    ) return "image/jpeg";
+    const ascii6 = header.subarray(0, 6).toString("ascii");
+    if (ascii6 === "GIF87a" || ascii6 === "GIF89a") return "image/gif";
+    if (
+      header.length >= 12
+      && header.subarray(0, 4).toString("ascii") === "RIFF"
+      && header.subarray(8, 12).toString("ascii") === "WEBP"
+    ) return "image/webp";
+    if (header.length >= 2 && header.subarray(0, 2).toString("ascii") === "BM") {
+      return "image/bmp";
+    }
+    return null;
+  } finally {
+    await handle.close();
+  }
+}
+
+function assetTokenFromPathname(pathname: string): string | null {
+  const remainder = pathname.slice(ANDROID_ASSET_ROUTE_PREFIX.length);
+  const token = remainder.split("/", 1)[0] ?? "";
+  return /^[a-zA-Z0-9_-]{32,128}$/.test(token) ? token : null;
+}
+
+/**
+ * Process-local, exact-file capabilities for Android image previews.
+ *
+ * Coil cannot attach the Android Remote bearer to a later image request, so
+ * the WebSocket RPC returns a short-lived opaque URL. The capability is bound
+ * to one canonical regular image inside the selected task's canonical root;
+ * no caller-controlled path is accepted by the HTTP route.
+ */
+export class AndroidRemoteAssetStore {
+  private readonly tickets = new Map<string, AndroidImageAsset>();
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  async issueWorkspaceImage(input: {
+    readonly workspaceRoot: string;
+    readonly path: string;
+  }): Promise<{ readonly relativeUrl: string; readonly expiresAt: number }> {
+    const workspaceRoot = input.workspaceRoot.trim();
+    const requestedPath = input.path.trim();
+    if (!workspaceRoot) throw new TypeError("The selected Codex task has no project folder");
+    if (!requestedPath) throw new TypeError("Image path is required");
+    if (requestedPath.length > 32 * 1024) throw new RangeError("Image path is too long");
+
+    const canonicalRoot = await realpath(resolve(workspaceRoot));
+    const unresolvedFile = isAbsolute(requestedPath)
+      ? resolve(requestedPath)
+      : resolve(canonicalRoot, requestedPath);
+    const canonicalFile = await realpath(unresolvedFile);
+    if (!pathIsWithinRoot(canonicalRoot, canonicalFile)) {
+      throw new TypeError("Image must be inside the selected Codex project folder");
+    }
+
+    return this.issueCanonicalImage(canonicalFile);
+  }
+
+  /**
+   * Issues an exact-file capability after the gateway has verified that the
+   * assistant explicitly referenced this absolute image in the selected task.
+   * Keeping that authorization in the gateway prevents the phone from using
+   * this method as a general-purpose laptop filesystem reader.
+   */
+  async issueAssistantReferencedImage(path: string): Promise<{
+    readonly relativeUrl: string;
+    readonly expiresAt: number;
+  }> {
+    const requestedPath = path.trim();
+    if (!requestedPath) throw new TypeError("Image path is required");
+    if (requestedPath.length > 32 * 1024) throw new RangeError("Image path is too long");
+    if (!isAbsolute(requestedPath)) {
+      throw new TypeError("An external assistant image must use an absolute path");
+    }
+    return this.issueCanonicalImage(await realpath(resolve(requestedPath)));
+  }
+
+  private async issueCanonicalImage(canonicalFile: string): Promise<{
+    readonly relativeUrl: string;
+    readonly expiresAt: number;
+  }> {
+    const file = await stat(canonicalFile);
+    if (!file.isFile()) throw new TypeError("Image path must point to a regular file");
+    if (file.size <= 0 || file.size > ANDROID_ASSET_MAX_BYTES) {
+      throw new RangeError("Image exceeds the 40 MB preview limit");
+    }
+    const mimeType = await imageMimeType(canonicalFile);
+    if (!mimeType) throw new TypeError("Image must be a PNG, JPEG, GIF, WebP, or BMP file");
+
+    this.prune();
+    while (this.tickets.size >= ANDROID_ASSET_MAX_TICKETS) {
+      const oldest = this.tickets.keys().next().value;
+      if (typeof oldest !== "string") break;
+      this.tickets.delete(oldest);
+    }
+    const token = randomBytes(24).toString("base64url");
+    const expiresAt = this.now() + ANDROID_ASSET_TTL_MS;
+    this.tickets.set(token, {
+      path: canonicalFile,
+      mimeType,
+      size: file.size,
+      expiresAt,
+    });
+    return {
+      relativeUrl: `${ANDROID_ASSET_ROUTE_PREFIX}${token}/${encodeURIComponent(basename(canonicalFile))}`,
+      expiresAt,
+    };
+  }
+
+  response(pathname: string, method: string): Response | null {
+    if (!pathname.startsWith(ANDROID_ASSET_ROUTE_PREFIX)) return null;
+    const token = assetTokenFromPathname(pathname);
+    if (!token) {
+      return new Response(null, {
+        status: 404,
+        headers: {
+          "Cache-Control": "no-store",
+          "X-Content-Type-Options": "nosniff",
+          "X-Frame-Options": "DENY",
+        },
+      });
+    }
+    const asset = this.tickets.get(token);
+    if (!asset || asset.expiresAt <= this.now()) {
+      if (asset) this.tickets.delete(token);
+      return new Response(null, {
+        status: 404,
+        headers: {
+          "Cache-Control": "no-store",
+          "X-Content-Type-Options": "nosniff",
+          "X-Frame-Options": "DENY",
+        },
+      });
+    }
+    if (method !== "GET" && method !== "HEAD") {
+      return new Response(null, {
+        status: 405,
+        headers: {
+          Allow: "GET, HEAD",
+          "Cache-Control": "no-store",
+          "X-Content-Type-Options": "nosniff",
+          "X-Frame-Options": "DENY",
+        },
+      });
+    }
+    return new Response(method === "HEAD" ? null : Bun.file(asset.path), {
+      status: 200,
+      headers: {
+        "Content-Type": asset.mimeType,
+        "Content-Length": String(asset.size),
+        "Cache-Control": "private, max-age=3600, immutable",
+        "Content-Disposition": `inline; filename*=UTF-8''${encodeURIComponent(basename(asset.path))}`,
+        "X-Content-Type-Options": "nosniff",
+        "X-Frame-Options": "DENY",
+      },
+    });
+  }
+
+  clear(): void {
+    this.tickets.clear();
+  }
+
+  private prune(): void {
+    const now = this.now();
+    for (const [token, asset] of this.tickets) {
+      if (asset.expiresAt <= now) this.tickets.delete(token);
+    }
+  }
+}

package/src/android-remote/attachments.ts

@@ -0,0 +1,168 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, extname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getConfigDir } from "../config";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { hardenSecretDir } from "../lib/windows-secret-acl";
+
+export const ANDROID_ATTACHMENT_MAX_COUNT = 8;
+export const ANDROID_ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+export const ANDROID_ATTACHMENT_MAX_TOTAL_BYTES = 40 * 1024 * 1024;
+const STAGED_FILE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+type JsonRecord = Record<string, unknown>;
+
+export type StagedAndroidAttachments = {
+  codexInputs: Array<{ type: "localImage"; path: string }>;
+  referencedFiles: string[];
+  stagedPaths: string[];
+};
+
+function record(value: unknown): JsonRecord | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as JsonRecord
+    : null;
+}
+
+function cleanFilename(value: unknown, fallback: string): string {
+  const raw = typeof value === "string" ? basename(value.trim()) : "";
+  const cleaned = raw.replace(/[^a-zA-Z0-9._ -]/g, "_").replace(/^\.+/, "").slice(0, 180);
+  return cleaned || fallback;
+}
+
+function decodeDataUrl(value: unknown): { mimeType: string; bytes: Buffer } {
+  if (typeof value !== "string") throw new TypeError("attachment data is missing");
+  const match = /^data:([^;,]{1,100});base64,([a-zA-Z0-9+/=\r\n]+)$/.exec(value);
+  if (!match) throw new TypeError("attachment must use a base64 data URL");
+  const bytes = Buffer.from(match[2]!.replace(/[\r\n]/g, ""), "base64");
+  if (bytes.length === 0 || bytes.length > ANDROID_ATTACHMENT_MAX_BYTES) {
+    throw new RangeError("attachment exceeds the 10 MB limit");
+  }
+  return { mimeType: match[1]!.toLowerCase(), bytes };
+}
+
+function isSupportedImage(mimeType: string, bytes: Buffer): boolean {
+  if (mimeType === "image/png") {
+    return bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+  }
+  if (mimeType === "image/jpeg") {
+    return bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff;
+  }
+  if (mimeType === "image/gif") {
+    const signature = bytes.subarray(0, 6).toString("ascii");
+    return signature === "GIF87a" || signature === "GIF89a";
+  }
+  if (mimeType === "image/webp") {
+    return bytes.length >= 12
+      && bytes.subarray(0, 4).toString("ascii") === "RIFF"
+      && bytes.subarray(8, 12).toString("ascii") === "WEBP";
+  }
+  return false;
+}
+
+function ensureFolder(path: string): void {
+  assertNotRealHomeUnderTest(path);
+  if (!existsSync(path)) mkdirSync(path, { recursive: true, mode: 0o700 });
+  try { chmodSync(path, 0o700); } catch { /* platform may ignore chmod */ }
+  if (process.platform === "win32") hardenSecretDir(path, { required: false });
+}
+
+export function androidAttachmentRoot(root = getConfigDir()): string {
+  return join(root, "android-remote-files");
+}
+
+/**
+ * Stages phone-owned attachment bytes under Remodex's protected data folder.
+ * Images become native Codex localImage inputs. Other file types are supported
+ * by the gateway contract and are added to the prompt as explicit PC-local paths.
+ */
+export function stageAndroidAttachments(input: {
+  clientId: string;
+  attachments: unknown;
+  root?: string;
+}): StagedAndroidAttachments {
+  if (!Array.isArray(input.attachments)) throw new TypeError("attachments must be an array");
+  if (input.attachments.length > ANDROID_ATTACHMENT_MAX_COUNT) {
+    throw new RangeError(`a prompt can contain at most ${ANDROID_ATTACHMENT_MAX_COUNT} attachments`);
+  }
+  const root = androidAttachmentRoot(input.root);
+  const clientFolder = join(root, input.clientId.replace(/[^a-zA-Z0-9._-]/g, "_"));
+  const turnFolder = join(clientFolder, randomUUID());
+  ensureFolder(turnFolder);
+
+  const codexInputs: StagedAndroidAttachments["codexInputs"] = [];
+  const referencedFiles: string[] = [];
+  const stagedPaths: string[] = [];
+  let totalBytes = 0;
+  try {
+    for (let index = 0; index < input.attachments.length; index += 1) {
+      const attachment = record(input.attachments[index]);
+      if (!attachment || (attachment.type !== "image" && attachment.type !== "file")) {
+        throw new TypeError("unsupported Android attachment type");
+      }
+      const decoded = decodeDataUrl(attachment.dataUrl);
+      const declaredMime = typeof attachment.mimeType === "string"
+        ? attachment.mimeType.trim().toLowerCase()
+        : decoded.mimeType;
+      if (declaredMime !== decoded.mimeType) throw new TypeError("attachment media type does not match its data");
+      if (attachment.type === "image" && !declaredMime.startsWith("image/")) {
+        throw new TypeError("image attachment must use an image media type");
+      }
+      if (attachment.type === "image" && !isSupportedImage(declaredMime, decoded.bytes)) {
+        throw new TypeError("image attachment must be a valid PNG, JPEG, GIF, or WebP file");
+      }
+      if (typeof attachment.sizeBytes === "number"
+        && Number.isFinite(attachment.sizeBytes)
+        && Math.abs(attachment.sizeBytes - decoded.bytes.length) > 3) {
+        throw new TypeError("attachment size does not match its data");
+      }
+      totalBytes += decoded.bytes.length;
+      if (totalBytes > ANDROID_ATTACHMENT_MAX_TOTAL_BYTES) {
+        throw new RangeError("combined attachments exceed the 40 MB limit");
+      }
+      const originalName = cleanFilename(attachment.name, `attachment-${index + 1}`);
+      const extension = extname(originalName).slice(0, 20);
+      const stem = basename(originalName, extension).slice(0, 120) || `attachment-${index + 1}`;
+      const path = join(turnFolder, `${stem}-${randomUUID()}${extension}`);
+      writeFileSync(path, decoded.bytes, { mode: 0o600, flag: "wx" });
+      try { chmodSync(path, 0o600); } catch { /* platform may ignore chmod */ }
+      stagedPaths.push(path);
+      if (attachment.type === "image") codexInputs.push({ type: "localImage", path });
+      else referencedFiles.push(path);
+    }
+    return { codexInputs, referencedFiles, stagedPaths };
+  } catch (error) {
+    try { rmSync(turnFolder, { recursive: true, force: true }); } catch { /* best-effort rollback */ }
+    throw error;
+  }
+}
+
+export function sweepOldAndroidAttachments(
+  root = androidAttachmentRoot(),
+  now = Date.now(),
+): void {
+  try {
+    if (!existsSync(root)) return;
+    for (const client of readdirSync(root, { withFileTypes: true })) {
+      if (!client.isDirectory()) continue;
+      const clientPath = join(root, client.name);
+      for (const turn of readdirSync(clientPath, { withFileTypes: true })) {
+        if (!turn.isDirectory()) continue;
+        const turnPath = join(clientPath, turn.name);
+        if (now - statSync(turnPath).mtimeMs > STAGED_FILE_TTL_MS) {
+          rmSync(turnPath, { recursive: true, force: true });
+        }
+      }
+    }
+  } catch {
+    // Attachment cleanup is maintenance. A locked file must not stop the gateway.
+  }
+}