hobots 5.0.0 → 5.1.0

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  Occurrence: () => Occurrence,
   captureException: () => captureException2,
   close: () => close2,
   default: () => src_default,
@@ -44,7 +45,7 @@ module.exports = __toCommonJS(src_exports);
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "5.0.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "5.1.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -357,6 +358,7 @@ var protocol_limits_default = {
   MAX_ITEM_PAYLOAD_BYTES: 16384,
   MAX_ITEM_COLUMNS: 12,
   MAX_ITEM_COLUMN_LABEL_CHARS: 60,
+  MAX_ITEMS_DONE_PER_PAGE: 1e3,
   MAX_ATTACHMENT_BYTES: 5242880,
   MAX_ATTACHMENTS_PER_RUN: 20,
   MAX_ATTACHMENTS_PER_LOG_ENTRY: 4,
@@ -1165,6 +1167,36 @@ var TasksApi = class {
       duplicates: typeof body?.duplicates === "number" ? body.duplicates : 0
     };
   }
+  /**
+   * Uma página dos ids já concluídos neste trabalho (`items.each` pula). Retry em falha
+   * de rede/5xx; 4xx é definitivo (404 = servidor sem o recurso).
+   */
+  async listDoneItems(runId, request) {
+    let response;
+    try {
+      response = await fetchWithRetry(
+        () => fetch(`${this.baseUrl}/${encodeURIComponent(runId)}/items/done`, {
+          redirect: "error",
+          method: "POST",
+          headers: this.headers(),
+          body: JSON.stringify(request),
+          signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS)
+        }),
+        { logger: this.logger, label: `itens conclu\xEDdos da run ${runId}` }
+      );
+    } catch (error) {
+      throw new Error(`consulta de itens conclu\xEDdos da run ${runId} descartada ap\xF3s retries: ${String(error)}`);
+    }
+    if (!response.ok) {
+      throw new TasksApiError(`consulta de itens conclu\xEDdos rejeitada (HTTP ${response.status})`, response.status);
+    }
+    const body = await response.json().catch(() => null);
+    if (!Array.isArray(body?.ids)) throw new TasksApiError("consulta de itens conclu\xEDdos: resposta malformada", 0);
+    return {
+      ids: body.ids.map((id) => String(id)),
+      next: typeof body.next === "string" && body.next.length > 0 ? body.next : null
+    };
+  }
   /**
    * Registra o anexo e obtém a URL presignada de upload. 404/501/503 significam
    * "esta instalação não tem anexos" — o RunReporter degrada em silêncio a partir daí.
@@ -1351,6 +1383,20 @@ var Backoff = class {
 };
 
 // src/tasks/errors.ts
+var Occurrence = class extends Error {
+  payload;
+  /** Print do item (bytes/caminho ou `hobots.image(...)`) — o `each` pendura no item. */
+  image;
+  constructor(message, payload, options) {
+    super(message);
+    this.name = "Occurrence";
+    this.payload = payload;
+    this.image = options?.image;
+  }
+};
+function isOccurrence(error) {
+  return error instanceof Error && error.name === "Occurrence";
+}
 function runCanceledError() {
   return Object.assign(new Error("execu\xE7\xE3o cancelada"), { name: "RunCanceled" });
 }
@@ -1367,1617 +1413,1745 @@ function isCancellation(error) {
   return error instanceof Error && (error.name === "RunCanceled" || error.name === "AbortError");
 }
 
-// src/tasks/each.ts
-function thrownMessage(error) {
-  if (error instanceof Error) return error.message || error.name;
-  return safeString(error);
-}
-var ItemHandle = class {
-  constructor(index, id, step, basePayload, sink) {
-    this.index = index;
-    this.id = id;
-    this.step = step;
-    this.basePayload = basePayload;
-    this.sink = sink;
-  }
-  index;
-  id;
-  step;
-  basePayload;
-  sink;
-  reported = false;
-  status;
-  succeeded(payload, options) {
-    this.record("succeeded", void 0, payload, options?.image);
-  }
-  failed(message, payload, options) {
-    this.record("failed", message, payload, options?.image);
-    if (this.step && this.step.status !== "error") this.step._setStatus("error", message);
-  }
-  occurrence(message, payload, options) {
-    this.record("occurrence", message, payload, options?.image);
-    if (this.step && this.step.status === "ok") this.step._setStatus("warning", message);
-  }
-  record(status, message, payload, image3) {
-    this.reported = true;
-    this.status = status;
-    const merged = { ...this.basePayload ?? {}, ...payload ?? {} };
-    this.sink.report(status, message, Object.keys(merged).length > 0 ? merged : void 0, this.id, image3);
+// src/tasks/attachments.ts
+var MAX_ATTACHMENT_BYTES = WIRE_LIMITS.MAX_ATTACHMENT_BYTES;
+var MAX_ATTACHMENTS_PER_RUN = WIRE_LIMITS.MAX_ATTACHMENTS_PER_RUN;
+var MAX_ATTACHMENTS_PER_LOG_ENTRY = WIRE_LIMITS.MAX_ATTACHMENTS_PER_LOG_ENTRY;
+var MAX_CONCURRENT_UPLOADS = 3;
+var MAX_CAPTION_CHARS = WIRE_LIMITS.MAX_CAPTION_CHARS;
+var ATTACHMENT_DRAIN_MS = 15e3;
+var IMAGE_BRAND = /* @__PURE__ */ Symbol.for("hobots.image");
+var ImageAttachment = class {
+  constructor(input, caption, contentType) {
+    this.input = input;
+    this.caption = caption;
+    this.contentType = contentType;
   }
+  input;
+  caption;
+  contentType;
+  [IMAGE_BRAND] = true;
 };
-function resolveId(options, element, index) {
-  const raw = options.id?.(element, index);
-  if (raw === null || raw === void 0) return void 0;
-  const text = safeString(raw);
-  return text.length > 0 ? text : void 0;
+function image(input, options = {}) {
+  return new ImageAttachment(input, options.caption, options.contentType);
 }
-function knownLength(list) {
-  const length = list?.length;
-  return typeof length === "number" && Number.isInteger(length) && length >= 1 ? length : void 0;
+function isImageAttachment(value) {
+  return typeof value === "object" && value !== null && value[IMAGE_BRAND] === true;
 }
-async function eachItem(list, handler, options, sink) {
-  const result = { total: 0, succeeded: 0, failed: 0, occurrence: 0 };
-  const length = options.progress === false ? void 0 : knownLength(list);
-  if (length !== void 0) sink.declareTotal(length);
-  let index = 0;
-  for await (const element of list) {
-    sink.checkCanceled();
-    const id = resolveId(options, element, index);
-    const description = options.description?.(element, index) ?? id ?? `#${index + 1}`;
-    const step = sink.startStep(options.op ?? "item", description);
-    const handle = new ItemHandle(index, id, step, options.payload?.(element, index), sink);
-    try {
-      await sink.stepScope(step, async () => handler(element, handle, index));
-      if (!handle.reported) handle.succeeded();
-    } catch (error) {
-      if (isTerminalError(error) || sink.isAborted()) {
-        step?._setStatus("cancelled")._close();
-        throw error;
-      }
-      const message = thrownMessage(error);
-      if (!handle.reported) handle.failed(message);
-      step?._failed(error);
-      sink.logError(`item ${description} falhou: ${message}`);
-    }
-    step?._close();
-    if (options.progress !== false) sink.advance();
-    result.total += 1;
-    result[handle.status ?? "succeeded"] += 1;
-    index += 1;
-    if (options.flush !== false) await sink.flush();
+function toImageAttachment(value) {
+  return isImageAttachment(value) ? value : new ImageAttachment(value);
+}
+async function readImageFile(path) {
+  if (!isNode()) {
+    throw new Error("caminho de arquivo s\xF3 \xE9 suportado em Node");
   }
-  return result;
+  const { readFile } = await import("fs/promises");
+  return new Uint8Array(await readFile(path));
 }
-
-// src/tasks/files.ts
-var LOCAL_FILES_DIR_ENV = "HOBOTS_LOCAL_FILES_DIR";
-var FILE_DOWNLOAD_IDLE_TIMEOUT_MS = 6e4;
-var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-function isFileRef(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const ref = value;
-  return typeof ref.id === "string" && typeof ref.name === "string" && typeof ref.size === "number" && typeof ref.contentType === "string" && (ref.storage === "s3" || ref.storage === "local");
+function startsWith(bytes, signature, offset = 0) {
+  if (bytes.length < offset + signature.length) return false;
+  return signature.every((byte, index) => bytes[offset + index] === byte);
 }
-function fileField(params, field) {
-  if (!Object.prototype.hasOwnProperty.call(params, field)) return void 0;
-  const value = params[field];
-  if (isFileRef(value)) return value;
-  if (Array.isArray(value) && value.every(isFileRef)) return value;
+var PNG_MAGIC = [137, 80, 78, 71, 13, 10, 26, 10];
+var MAX_PNG_DIMENSION = WIRE_LIMITS.MAX_IMAGE_DIMENSION_PX;
+var JPEG_MAGIC = [255, 216, 255];
+var RIFF_MAGIC = [82, 73, 70, 70];
+var WEBP_MAGIC = [87, 69, 66, 80];
+function sniffContentType(bytes) {
+  if (startsWith(bytes, PNG_MAGIC)) return "image/png";
+  if (startsWith(bytes, JPEG_MAGIC)) return "image/jpeg";
+  if (startsWith(bytes, RIFF_MAGIC) && startsWith(bytes, WEBP_MAGIC, 8)) return "image/webp";
   return void 0;
 }
-function collectFileRefs(params) {
-  const refs = [];
-  for (const field of Object.keys(params)) {
-    const value = fileField(params, field);
-    if (value !== void 0) refs.push(...Array.isArray(value) ? value : [value]);
-  }
-  return refs;
+function readPngDimensions(bytes) {
+  if (!startsWith(bytes, PNG_MAGIC) || bytes.length < 24) return void 0;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const width = view.getUint32(16);
+  const height = view.getUint32(20);
+  if (width === 0 || height === 0) return void 0;
+  if (width > MAX_PNG_DIMENSION || height > MAX_PNG_DIMENSION) return void 0;
+  return { width, height };
 }
-function safeFileName(name, fallback) {
-  const cleaned = name.replace(/^.*[\\/]/, "").replace(/[\u0000-\u001f<>:"|?*]/g, "_").trim();
-  return cleaned === "" || cleaned === "." || cleaned === ".." ? fallback : cleaned;
+async function toBytes(input) {
+  if (typeof input === "string") return readImageFile(input);
+  if (input instanceof Uint8Array) return input;
+  return new Uint8Array(input);
 }
-function isInsideDir(root, candidate, sep) {
-  const base = root.endsWith(sep) ? root : root + sep;
-  return candidate.startsWith(base) && candidate.length > base.length;
+
+// src/tasks/run-context-store.ts
+var storage;
+var stepStorage;
+var initPromise;
+async function ensureStorage() {
+  if (storage || !isNode()) return;
+  initPromise ??= import("async_hooks").then(({ AsyncLocalStorage: ALS }) => {
+    storage = new ALS();
+    stepStorage = new ALS();
+  });
+  await initPromise;
 }
-function unavailableLocal(ref) {
-  return new Error(`arquivo "${ref.name}" enviado pelo Studio de outro computador ou j\xE1 consumido`);
+async function runWithRunContext(store, fn) {
+  await ensureStorage();
+  return storage ? storage.run(store, fn) : fn();
 }
-function localRunPath(ref) {
-  if (!isLocalRun()) return void 0;
-  const path = ref.path;
-  return typeof path === "string" && path.trim() !== "" ? path : void 0;
+function currentRunReporter() {
+  return storage?.getStore()?.reporter;
 }
-function errorCode(error) {
-  return error?.code;
+async function runWithStepScope(scope, fn) {
+  await ensureStorage();
+  return stepStorage ? stepStorage.run(scope, fn) : fn();
 }
-var RunFileStore = class {
-  constructor(deps) {
-    this.deps = deps;
-    this.files = {
-      list: () => collectFileRefs(deps.params),
-      get: (field) => fileField(deps.params, field),
-      // async: erro de uso (campo sem arquivo, valor inválido) chega como Promise rejeitada, nunca síncrono
-      download: async (refOrField, options) => this.download(this.single(refOrField), options?.dest),
-      downloadAll: async (field, options) => this.downloadAll(field, options?.dest),
-      read: async (refOrField) => this.read(this.single(refOrField))
-    };
-  }
-  deps;
-  files;
-  tempDir;
-  /** Apaga a pasta temporária da execução (cópias que o bot não levou para `dest`). Nunca lança. */
-  async cleanup() {
-    const pending = this.tempDir;
-    this.tempDir = void 0;
-    if (!pending) return;
+function currentStep(transaction) {
+  const scope = stepStorage?.getStore();
+  return scope?.transaction === transaction ? scope.step : void 0;
+}
+
+// src/retry.ts
+var DEFAULT_RETRIES = 3;
+var DEFAULT_DELAY_MS = 1e3;
+function resolveDelay(delay, attempt, fallbackMs) {
+  const value = typeof delay === "function" ? delay(attempt) : delay ?? fallbackMs;
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+async function retryWithBackoff(fn, options = {}) {
+  const requested = options.retries ?? DEFAULT_RETRIES;
+  const retries = Number.isFinite(requested) ? Math.max(0, Math.floor(requested)) : DEFAULT_RETRIES;
+  const wait = options.wait ?? sleep;
+  for (let attempt = 1; ; attempt++) {
+    if (options.signal?.aborted) throw runCanceledError();
     try {
-      const { rm } = await import("fs/promises");
-      await rm(await pending, { recursive: true, force: true });
-    } catch {
-    }
-  }
-  field(field) {
-    const value = fileField(this.deps.params, field);
-    if (value === void 0) throw new Error(`campo "${field}" n\xE3o tem arquivo nos params`);
-    return value;
-  }
-  single(refOrField) {
-    if (typeof refOrField === "string") {
-      const value = this.field(refOrField);
-      if (Array.isArray(value)) {
-        throw new Error(`campo "${refOrField}" tem v\xE1rios arquivos \u2014 use downloadAll("${refOrField}") ou passe um item da lista`);
-      }
-      return value;
+      return await fn(attempt);
+    } catch (error) {
+      const exhausted = attempt > retries;
+      const retriable = !isTerminalError(error) && !options.signal?.aborted && (options.shouldRetry?.(error) ?? true);
+      if (exhausted || !retriable) throw error;
+      const delay = resolveDelay(options.delayMs, attempt, DEFAULT_DELAY_MS);
+      options.onRetry?.(error, attempt, delay);
+      await wait(delay);
     }
-    if (!isFileRef(refOrField)) throw new TypeError("esperado um FileRef ou o nome de um campo de arquivo");
-    return refOrField;
   }
-  async downloadAll(field, dest) {
-    const value = this.field(field);
-    const refs = Array.isArray(value) ? value : [value];
-    const paths = [];
-    for (const ref of refs) paths.push(await this.download(ref, dest, true));
-    return paths;
+}
+
+// src/transaction.ts
+var FLUSH_TRANSACTION_OP = "hobots.run.flush";
+var DEFAULT_STEP_RETRIES = 1;
+var DEFAULT_STEP_RETRY_DELAY_MS = 5e3;
+var MAX_STEP_MESSAGE_CHARS = 2e3;
+var MAX_BACKLOG = 100;
+function stepMessage(text) {
+  return clip(scrubSecrets(text), MAX_STEP_MESSAGE_CHARS);
+}
+function stepId() {
+  return uuid4().slice(0, 16);
+}
+function stepLabel(op, description) {
+  return [op, description].filter(Boolean).join(" \u2014 ") || "(sem nome)";
+}
+function errorText(error) {
+  if (error instanceof Error) return error.message || error.name;
+  return safeString(error);
+}
+function errorReason(error) {
+  return error instanceof Error ? `${error.name}: ${errorText(error)}` : errorText(error);
+}
+function levelForStatus(status) {
+  switch (status) {
+    case "warning":
+      return "warning";
+    case "error":
+      return "error";
+    case "cancelled":
+      return "warning";
+    default:
+      return "success";
   }
-  async read(ref) {
-    const { readFile, rm } = await import("fs/promises");
-    const { dirname } = await import("path");
-    const path = await this.download(ref, void 0);
-    try {
-      return await readFile(path);
-    } finally {
-      await rm(dirname(path), { recursive: true, force: true });
-    }
+}
+function colorForStatus(status) {
+  switch (status) {
+    case "warning":
+      return "yellow";
+    case "error":
+      return "red";
+    case "cancelled":
+      return "gray";
+    default:
+      return "green";
   }
-  async download(ref, dest, destIsDir = false) {
-    this.checkCanceled();
-    const target = await this.resolveTarget(ref, dest, destIsDir);
-    if (ref.storage === "local") await this.copyLocal(ref, target);
-    else await this.downloadS3(ref, target);
-    return target;
+}
+var Step = class {
+  constructor(transaction, parentStepId, op, description) {
+    this.transaction = transaction;
+    this.parentStepId = parentStepId;
+    this.op = op;
+    this.description = description;
   }
-  checkCanceled() {
-    if (this.deps.signal.aborted) throw runCanceledError();
+  transaction;
+  parentStepId;
+  op;
+  description;
+  stepId = stepId();
+  startTimestamp = nowISO();
+  status = "ok";
+  endTimestamp;
+  _data;
+  // ── API do bot ────────────────────────────────────────────────────────────
+  warning(message, options) {
+    if (this.status !== "error") this._setStatus("warning", message);
+    if (options?.image !== void 0) this.attachImage(options.image);
+    return this;
   }
-  runTempDir() {
-    this.tempDir ??= (async () => {
-      const { mkdtemp } = await import("fs/promises");
-      const { tmpdir } = await import("os");
-      const { join } = await import("path");
-      return mkdtemp(join(tmpdir(), "hobots-files-"));
-    })();
-    return this.tempDir;
+  image(image3) {
+    this.attachImage(image3);
+    return this;
   }
-  async resolveTarget(ref, dest, destIsDir) {
-    const { mkdir, mkdtemp, stat } = await import("fs/promises");
-    const { dirname, join, resolve: resolve2 } = await import("path");
-    const name = safeFileName(ref.name, "arquivo");
-    if (dest === void 0) {
-      return join(await mkdtemp(join(await this.runTempDir(), "f-")), name);
-    }
-    const isDir = destIsDir || dest.endsWith("/") || dest.endsWith("\\") || (await stat(dest).catch(() => void 0))?.isDirectory() === true;
-    if (isDir) {
-      await mkdir(dest, { recursive: true });
-      return resolve2(dest, name);
-    }
-    await mkdir(dirname(resolve2(dest)), { recursive: true });
-    return resolve2(dest);
+  data(key, value) {
+    if (key === "attachments") return this;
+    this._setData(key, value);
+    return this;
   }
-  /** storage 's3': URL pré-assinada → GET em streaming → confere o tamanho → só então DELETE. */
-  async downloadS3(ref, target) {
-    const { api, runId, signal } = this.deps;
-    let expected;
-    let url;
-    try {
-      const info = await api.requestFileDownload(runId, ref.id, signal);
-      expected = info.size >= 0 ? info.size : ref.size;
-      url = info.url;
-    } catch (error) {
-      throw this.translate(error, ref);
-    }
-    const { open, rename, rm } = await import("fs/promises");
-    const part = `${target}.part`;
-    const idleTimeoutMs = this.deps.idleTimeoutMs ?? FILE_DOWNLOAD_IDLE_TIMEOUT_MS;
-    const controller = new AbortController();
-    let timedOut = false;
-    let timer;
-    const arm = () => {
-      clearTimeout(timer);
-      timer = setTimeout(() => {
-        timedOut = true;
-        controller.abort();
-      }, idleTimeoutMs);
-    };
-    const onCancel = () => controller.abort();
-    signal.addEventListener("abort", onCancel, { once: true });
-    try {
-      arm();
-      const response = await api.fetchFile(url, controller.signal);
-      const handle = await open(part, "w");
-      let written = 0;
-      try {
-        const reader = response.body?.getReader();
-        const stopReading = () => void reader?.cancel().catch(() => void 0);
-        controller.signal.addEventListener("abort", stopReading, { once: true });
-        for (; ; ) {
-          const chunk = reader ? await reader.read() : { done: true, value: void 0 };
-          if (chunk.done) break;
-          arm();
-          written += chunk.value.byteLength;
-          if (written > expected) {
-            stopReading();
-            break;
-          }
-          await handle.write(chunk.value);
-        }
-      } finally {
-        await handle.close();
-      }
-      if (written !== expected) {
-        throw new Error(`tamanho divergente no download de "${ref.name}": recebidos ${written} bytes, esperados ${expected}`);
-      }
-      await rename(part, target);
-    } catch (error) {
-      await rm(part, { force: true });
-      if (signal.aborted) throw runCanceledError();
-      if (timedOut) {
-        throw new Error(`download de "${ref.name}" parado h\xE1 ${idleTimeoutMs / 1e3}s \u2014 tente de novo`);
-      }
-      throw this.translate(error, ref);
-    } finally {
-      clearTimeout(timer);
-      signal.removeEventListener("abort", onCancel);
-    }
-    try {
-      await api.confirmFileDownload(runId, ref.id);
-    } catch (error) {
-      this.deps.warn(`arquivo "${ref.name}" baixado, mas a confirma\xE7\xE3o ao servidor falhou: ${String(error)}`);
-    }
+  // ── Internos (chamados pelo SDK) ──────────────────────────────────────────
+  /** `data` da etapa como vai no wire (undefined quando vazio). */
+  get payload() {
+    return this._data;
+  }
+  _setStatus(status, message) {
+    this.status = status;
+    if (message) this._setData("message", stepMessage(safeString(message)));
+    return this;
   }
   /**
-   * storage 'local': copia o único arquivo de `$HOBOTS_LOCAL_FILES_DIR/<id>/` e apaga a pasta de
-   * origem. No modo local, um FileRef com `path` copia direto desse caminho, sem apagar a origem.
+   * Marca `error` guardando `{ type, message }` em `data.error` e fecha a etapa. Aceita qualquer
+   * valor lançado; `message` sobrescreve a mensagem do erro. Numa etapa já fechada não faz nada.
    */
-  async copyLocal(ref, target) {
-    const direct = localRunPath(ref);
-    if (direct !== void 0) {
-      await this.copyFromPath(ref, direct, target);
-      return;
-    }
-    const base = process.env[LOCAL_FILES_DIR_ENV];
-    if (!base) throw unavailableLocal(ref);
-    const { copyFile, readdir, rename, rm, stat } = await import("fs/promises");
-    const { join, resolve: resolve2, sep } = await import("path");
-    const root = resolve2(base);
-    const folder = resolve2(root, ref.id);
-    if (!isInsideDir(root, folder, sep) || !UUID_RE.test(ref.id)) {
-      throw new Error(`id de arquivo local inv\xE1lido: ${JSON.stringify(ref.id)}`);
-    }
-    let names;
-    try {
-      names = (await readdir(folder, { withFileTypes: true })).filter((entry) => entry.isFile()).map((entry) => entry.name);
-    } catch (error) {
-      if (errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR") throw unavailableLocal(ref);
-      throw error;
-    }
-    if (names.length === 0) throw unavailableLocal(ref);
-    if (names.length > 1) throw new Error(`pasta do arquivo "${ref.name}" tem ${names.length} arquivos \u2014 esperado 1`);
-    this.checkCanceled();
-    const part = `${target}.part`;
-    try {
-      await copyFile(join(folder, names[0]), part);
-      const { size } = await stat(part);
-      if (size !== ref.size) {
-        throw new Error(`tamanho divergente na c\xF3pia de "${ref.name}": copiados ${size} bytes, esperados ${ref.size}`);
-      }
-      await rename(part, target);
-    } catch (error) {
-      await rm(part, { force: true });
-      throw error;
-    }
-    await rm(folder, { recursive: true, force: true });
+  _failed(error, message) {
+    if (this.endTimestamp) return this;
+    this.status = "error";
+    const type = error instanceof Error ? error.name : typeof error === "object" && error !== null ? "Error" : void 0;
+    const raw = message ?? errorText(error);
+    this._setData("error", { ...type ? { type } : {}, message: stepMessage(safeString(raw)) });
+    this._close();
+    return this;
+  }
+  _setData(key, value) {
+    this._data = { ...this._data, [key]: value };
+  }
+  _deleteData(key) {
+    if (!this._data || !(key in this._data)) return;
+    const rest = { ...this._data };
+    delete rest[key];
+    this._data = Object.keys(rest).length > 0 ? rest : void 0;
   }
   /**
-   * Modo local: cópia do arquivo apontado por `path` (teste roda várias vezes — a fonte fica).
-   * Sem conferência de tamanho: o `size` do FileRef é informativo aqui.
+   * Dispara o upload pela run (sink do RunReporter) e referencia o anexo em
+   * `data.attachments` (chave reservada; teto igual ao das linhas de log). Fora de uma
+   * run não há onde pendurar a imagem — descarta com aviso único.
    */
-  async copyFromPath(ref, path, target) {
-    const { copyFile, rename, rm, stat } = await import("fs/promises");
-    const { resolve: resolve2 } = await import("path");
-    const source = resolve2(path);
-    const info = await stat(source).catch(() => void 0);
-    if (!info?.isFile()) throw new Error(`arquivo "${ref.name}" n\xE3o encontrado em ${path}`);
-    this.checkCanceled();
-    const part = `${target}.part`;
-    try {
-      await copyFile(source, part);
-      await rename(part, target);
-    } catch (error) {
-      await rm(part, { force: true });
-      throw error;
-    }
+  attachImage(image3) {
+    const current = Array.isArray(this._data?.attachments) ? this._data.attachments : [];
+    if (current.length >= MAX_ATTACHMENTS_PER_LOG_ENTRY) return;
+    const id = this.transaction.attachImage(image3);
+    if (!id) return;
+    this._setData("attachments", [...current, id]);
   }
-  translate(error, ref) {
-    if (this.deps.signal.aborted) return runCanceledError();
-    if (error instanceof TasksApiError && error.status === 410) {
-      return new TasksApiError(`arquivo "${ref.name}" j\xE1 baixado ou expirado`, 410);
+  /** Motivo registrado (warning/erro) — usado no log de FINISH. */
+  reason() {
+    const error = this._data?.error;
+    const text = typeof error?.message === "string" ? error.message : this._data?.message;
+    return typeof text === "string" && text ? text : void 0;
+  }
+  /** Fecha a etapa mantendo o status que estiver. Idempotente. */
+  _close() {
+    if (this.endTimestamp) return;
+    this.endTimestamp = nowISO();
+    this.transaction.emit(
+      "step",
+      "finish",
+      stepLabel(this.op, this.description),
+      this.startTimestamp,
+      this.endTimestamp,
+      this.status,
+      this.reason()
+    );
+  }
+  toJSON() {
+    return {
+      step_id: this.stepId,
+      ...this.parentStepId ? { parent_step_id: this.parentStepId } : {},
+      ...this.op ? { op: clip(this.op, MAX_STEP_OP_CHARS) } : {},
+      ...this.description ? { description: clip(this.description, MAX_STEP_DESCRIPTION_CHARS) } : {},
+      status: this.status,
+      start_timestamp: this.startTimestamp,
+      timestamp: this.endTimestamp ?? nowISO(),
+      ...this._data ? { data: this._data } : {}
+    };
+  }
+};
+var Transaction = class {
+  constructor(client, name, op, runId, options = {}) {
+    this.client = client;
+    this.name = name;
+    this.op = op;
+    this.runId = runId;
+    this.echo = options.echo ?? false;
+    this.emit("transaction", "start", op ? `${name} (${op})` : name);
+  }
+  client;
+  name;
+  op;
+  runId;
+  eventId = uuid4();
+  stepId = stepId();
+  startTimestamp = nowISO();
+  status = "ok";
+  steps = [];
+  finished = false;
+  lifecycleSink;
+  attachmentSink;
+  warnedNoAttachmentSink = false;
+  // instalado pelo RunReporter: abrir uma etapa é um ponto de parada cooperativo (lança RunCanceled)
+  stepGuard;
+  // modo local (sem client): o FINISH de cada etapa sai no terminal, como `[hobots:item]`
+  echo;
+  // eventos emitidos antes do sink existir (o START da transaction sai no construtor,
+  // antes do RunReporter conectar) — replay no setLifecycleSink
+  lifecycleBacklog = [];
+  // ── Lifecycle / eco ───────────────────────────────────────────────────────
+  /**
+   * Registra o início/fim de uma etapa ou da transaction: espelha a linha no sink de
+   * lifecycle, se conectado (é assim que os eventos de performance aparecem nos logs da
+   * run no app), e ecoa no terminal com `debug: true` — ou, no modo local, só o FINISH das
+   * etapas (`[hobots:step] FINISH …`), para o Studio e o dev verem.
+   */
+  emit(kind, phase, label, startTs, endTs, status, reason) {
+    const durationMs = startTs && endTs ? new Date(endTs).getTime() - new Date(startTs).getTime() : void 0;
+    const suffix = (durationMs != null ? ` (${durationMs}ms)` : "") + (reason ? `: ${reason}` : "");
+    const localFinish = this.echo && kind === "step" && phase === "finish";
+    if (this.client?.debug || localFinish) {
+      const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
+      console.log(`${tag} ${label}${suffix}`);
     }
-    if (error instanceof TasksApiError && error.status === 404) {
-      return new TasksApiError(`arquivo "${ref.name}" n\xE3o encontrado nesta execu\xE7\xE3o`, 404);
+    const level = phase === "finish" ? levelForStatus(status ?? "ok") : "info";
+    const message = `[${kind}] ${phase.toUpperCase()} ${label}${suffix}`;
+    if (this.lifecycleSink) this.lifecycleSink(level, message);
+    else if (this.lifecycleBacklog.length < MAX_BACKLOG) this.lifecycleBacklog.push([level, message]);
+  }
+  /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
+  setLifecycleSink(sink) {
+    this.lifecycleSink = sink;
+    const backlog = this.lifecycleBacklog;
+    this.lifecycleBacklog = [];
+    for (const [level, message] of backlog) sink(level, message);
+  }
+  /** Conecta o pipeline de anexos da run — é o que dá imagem às etapas. */
+  setAttachmentSink(sink) {
+    this.attachmentSink = sink;
+  }
+  /** Imagem de uma etapa → id do anexo pela run; sem run, descarta com aviso único. */
+  attachImage(image3) {
+    if (this.attachmentSink) return this.attachmentSink(image3, nowISO());
+    if (!this.warnedNoAttachmentSink) {
+      this.warnedNoAttachmentSink = true;
+      console.warn("[hobots] imagem de etapa descartada \u2014 s\xF3 \xE9 suportada dentro de uma execu\xE7\xE3o");
     }
-    return error;
+    return void 0;
   }
-};
-
-// src/retry.ts
-var DEFAULT_RETRIES = 3;
-var DEFAULT_DELAY_MS = 1e3;
-function resolveDelay(delay, attempt, fallbackMs) {
-  const value = typeof delay === "function" ? delay(attempt) : delay ?? fallbackMs;
-  return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
-}
-async function retryWithBackoff(fn, options = {}) {
-  const requested = options.retries ?? DEFAULT_RETRIES;
-  const retries = Number.isFinite(requested) ? Math.max(0, Math.floor(requested)) : DEFAULT_RETRIES;
-  const wait = options.wait ?? sleep;
-  for (let attempt = 1; ; attempt++) {
-    if (options.signal?.aborted) throw runCanceledError();
+  // ── Etapas ────────────────────────────────────────────────────────────────
+  /**
+   * Conecta a checagem de cancelamento chamada antes de cada etapa nova (inclusive antes de
+   * cada nova tentativa) — é assim que `hobots.step()` para uma run cancelada.
+   */
+  setStepGuard(guard) {
+    this.stepGuard = guard;
+  }
+  /** A etapa aberta por `step()` (ou `items.each`) no contexto async atual, se houver. */
+  currentStep() {
+    return currentStep(this);
+  }
+  /** Faz de `step` a etapa corrente durante `fn` (filhas aninham nela). Sem etapa, só roda `fn`. */
+  scope(step, fn) {
+    if (!step) return fn();
+    return runWithStepScope({ transaction: this, step }, fn);
+  }
+  /** Abre uma etapa sob a corrente (ou direta da transaction). Interno: o bot usa `step()`. */
+  start(op, description) {
+    this.stepGuard?.();
+    const parent = this.currentStep();
+    const step = new Step(this, parent ? parent.stepId : this.stepId, op, description);
+    this.steps.push(step);
+    this.emit("step", "start", stepLabel(op, description));
+    return step;
+  }
+  /**
+   * Registra a etapa `name` executando `fn(etapa)` até dar certo ou esgotar `retries`
+   * tentativas extras (default 1), esperando `retryDelayMs` entre elas (default 5 000).
+   * Resolve com o retorno de `fn`.
+   *
+   * Uma etapa só no waterfall, cobrindo todas as tentativas: `data.attempts` quando houve
+   * mais de uma; `warning` com o motivo quando a última deu certo; `error` (e a exceção
+   * sobe) quando esgotou; `cancelled` em cancelamento/timeout, que nunca repetem.
+   */
+  async step(name, fn, options = {}) {
+    const requested = options.retries ?? DEFAULT_STEP_RETRIES;
+    const totalRetries = Number.isFinite(requested) ? Math.max(0, Math.floor(requested)) : DEFAULT_STEP_RETRIES;
+    const step = this.start(void 0, safeString(name));
+    let attempts = 0;
+    let lastFailure;
     try {
-      return await fn(attempt);
+      const result = await retryWithBackoff(
+        (attempt) => {
+          attempts = attempt;
+          return this.scope(step, async () => fn(step));
+        },
+        {
+          retries: totalRetries,
+          delayMs: (attempt) => resolveDelay(options.retryDelayMs, attempt, DEFAULT_STEP_RETRY_DELAY_MS),
+          signal: options.signal,
+          wait: options.wait,
+          onRetry: (error, attempt, delayMs) => {
+            lastFailure = { error };
+            options.warn?.(
+              `etapa "${step.description}": tentativa ${attempt}/${totalRetries + 1} falhou: ${truncate(errorReason(error), 500)} \u2014 nova tentativa em ${delayMs}ms`
+            );
+          }
+        }
+      );
+      this.noteAttempts(step, attempts);
+      if (lastFailure && step.status === "ok") {
+        step._setStatus("warning", `tentativa ${attempts - 1}/${totalRetries + 1} falhou: ${errorReason(lastFailure.error)}`);
+      }
+      step._close();
+      return result;
     } catch (error) {
-      const exhausted = attempt > retries;
-      const retriable = !isTerminalError(error) && !options.signal?.aborted && (options.shouldRetry?.(error) ?? true);
-      if (exhausted || !retriable) throw error;
-      const delay = resolveDelay(options.delayMs, attempt, DEFAULT_DELAY_MS);
-      options.onRetry?.(error, attempt, delay);
-      await wait(delay);
+      this.noteAttempts(step, attempts);
+      if (isTerminalError(error)) step._setStatus("cancelled")._close();
+      else step._failed(error);
+      throw error;
     }
   }
-}
-
-// src/tasks/attachments.ts
-var MAX_ATTACHMENT_BYTES = WIRE_LIMITS.MAX_ATTACHMENT_BYTES;
-var MAX_ATTACHMENTS_PER_RUN = WIRE_LIMITS.MAX_ATTACHMENTS_PER_RUN;
-var MAX_ATTACHMENTS_PER_LOG_ENTRY = WIRE_LIMITS.MAX_ATTACHMENTS_PER_LOG_ENTRY;
-var MAX_CONCURRENT_UPLOADS = 3;
-var MAX_CAPTION_CHARS = WIRE_LIMITS.MAX_CAPTION_CHARS;
-var ATTACHMENT_DRAIN_MS = 15e3;
-var IMAGE_BRAND = /* @__PURE__ */ Symbol.for("hobots.image");
-var ImageAttachment = class {
-  constructor(input, caption, contentType) {
-    this.input = input;
-    this.caption = caption;
-    this.contentType = contentType;
+  noteAttempts(step, attempts) {
+    if (attempts > 1) step._setData("attempts", attempts);
   }
-  input;
-  caption;
-  contentType;
-  [IMAGE_BRAND] = true;
-};
-function image(input, options = {}) {
-  return new ImageAttachment(input, options.caption, options.contentType);
-}
-function isImageAttachment(value) {
-  return typeof value === "object" && value !== null && value[IMAGE_BRAND] === true;
-}
-function toImageAttachment(value) {
-  return isImageAttachment(value) ? value : new ImageAttachment(value);
-}
-async function readImageFile(path) {
-  if (!isNode()) {
-    throw new Error("caminho de arquivo s\xF3 \xE9 suportado em Node");
-  }
-  const { readFile } = await import("fs/promises");
-  return new Uint8Array(await readFile(path));
-}
-function startsWith(bytes, signature, offset = 0) {
-  if (bytes.length < offset + signature.length) return false;
-  return signature.every((byte, index) => bytes[offset + index] === byte);
-}
-var PNG_MAGIC = [137, 80, 78, 71, 13, 10, 26, 10];
-var MAX_PNG_DIMENSION = WIRE_LIMITS.MAX_IMAGE_DIMENSION_PX;
-var JPEG_MAGIC = [255, 216, 255];
-var RIFF_MAGIC = [82, 73, 70, 70];
-var WEBP_MAGIC = [87, 69, 66, 80];
-function sniffContentType(bytes) {
-  if (startsWith(bytes, PNG_MAGIC)) return "image/png";
-  if (startsWith(bytes, JPEG_MAGIC)) return "image/jpeg";
-  if (startsWith(bytes, RIFF_MAGIC) && startsWith(bytes, WEBP_MAGIC, 8)) return "image/webp";
-  return void 0;
-}
-function readPngDimensions(bytes) {
-  if (!startsWith(bytes, PNG_MAGIC) || bytes.length < 24) return void 0;
-  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  const width = view.getUint32(16);
-  const height = view.getUint32(20);
-  if (width === 0 || height === 0) return void 0;
-  if (width > MAX_PNG_DIMENSION || height > MAX_PNG_DIMENSION) return void 0;
-  return { width, height };
-}
-async function toBytes(input) {
-  if (typeof input === "string") return readImageFile(input);
-  if (input instanceof Uint8Array) return input;
-  return new Uint8Array(input);
-}
-
-// src/tasks/context.ts
-var LOG_LEVEL_COLOR = {
-  debug: "gray",
-  info: "cyan",
-  warning: "yellow",
-  error: "red",
-  success: "green"
-};
-function joinLogArgs(message, rest) {
-  if (rest.length === 0) return safeString(message);
-  return [message, ...rest].map(safeString).join(" ");
-}
-function splitLogArgs(message, rest) {
-  const args = [message, ...rest];
-  const last = args[args.length - 1];
-  if (!isImageAttachment(last)) return { text: joinLogArgs(message, rest) };
-  const text = args.slice(0, -1);
-  if (text.length === 0) return { text: last.caption !== void 0 ? safeString(last.caption) : "captura de tela", image: last };
-  return { text: joinLogArgs(text[0], text.slice(1)), image: last };
-}
-function printRunLog(level, message) {
-  const line = colorize(`[hobots] ${level.toUpperCase()}`, LOG_LEVEL_COLOR[level]);
-  const method2 = level === "warning" ? "warn" : level === "success" ? "info" : level;
-  console[method2](line, message);
-}
-var PROGRESS_LINE_PREFIX = "[hobots:progress]";
-var PROGRESS_PRINT_THROTTLE_MS = 250;
-function printRunProgress(current, total) {
-  console.log(`${PROGRESS_LINE_PREFIX} ${current}/${total}`);
-}
-function cancelableSleep(ms, signal) {
-  return new Promise((resolve2, reject) => {
-    if (signal.aborted) {
-      reject(runCanceledError());
-      return;
-    }
-    const onAbort = () => {
-      clearTimeout(timer);
-      reject(runCanceledError());
-    };
-    const timer = setTimeout(() => {
-      signal.removeEventListener("abort", onAbort);
-      resolve2();
-    }, ms);
-    signal.addEventListener("abort", onAbort, { once: true });
-  });
-}
-var DEFAULT_LOG_FLUSH_INTERVAL_MS = 2e3;
-var DEFAULT_CANCEL_CHECK_INTERVAL_MS = 5e3;
-var MIN_CANCEL_CHECK_INTERVAL_MS = 1e3;
-var MAX_CANCEL_CHECK_INTERVAL_MS = 15e3;
-var MAX_LOG_MESSAGE_CHARS = WIRE_LIMITS.MAX_LOG_MESSAGE_CHARS;
-var MAX_LOGS_PER_PATCH = WIRE_LIMITS.MAX_LOGS_PER_PATCH;
-var FLUSH_AT_BUFFERED = 20;
-var MAX_ITEMS_PER_REQUEST = WIRE_LIMITS.MAX_ITEMS_PER_REQUEST;
-var MAX_ITEM_MESSAGE_CHARS = WIRE_LIMITS.MAX_ITEM_MESSAGE_CHARS;
-var MAX_ITEM_PAYLOAD_BYTES = WIRE_LIMITS.MAX_ITEM_PAYLOAD_BYTES;
-var ITEMS_FLUSH_AT_BUFFERED = 100;
-var ITEMS_DRAIN_MS = 15e3;
-var PROGRESS_FLUSH_MS = 1e3;
-function scrubPayloadValue(value, depth) {
-  if (typeof value === "string") return scrubSecrets(value);
-  if (depth >= 4 || value === null || typeof value !== "object") return value;
-  if (Array.isArray(value)) return value.map((entry) => scrubPayloadValue(entry, depth + 1));
-  const out = {};
-  for (const [key, entry] of Object.entries(value)) {
-    out[key] = scrubPayloadValue(entry, depth + 1);
-  }
-  return out;
-}
-var RunReporter = class {
-  constructor(api, runId, logger, tx, flushIntervalMs, cancelCheckIntervalMs, params = {}) {
-    this.api = api;
-    this.runId = runId;
-    this.logger = logger;
-    this.tx = tx;
-    this.flushIntervalMs = flushIntervalMs ?? DEFAULT_LOG_FLUSH_INTERVAL_MS;
-    this.cancelCheckIntervalMs = Math.min(
-      MAX_CANCEL_CHECK_INTERVAL_MS,
-      Math.max(MIN_CANCEL_CHECK_INTERVAL_MS, cancelCheckIntervalMs ?? DEFAULT_CANCEL_CHECK_INTERVAL_MS)
-    );
-    const logAt = (level) => (message, ...rest) => {
-      const { text, image: image3 } = splitLogArgs(message, rest);
-      this.log(level, text, image3);
-    };
-    const log = {
-      debug: logAt("debug"),
-      info: logAt("info"),
-      warn: logAt("warning"),
-      error: logAt("error"),
-      success: logAt("success")
-    };
-    tx.setLifecycleSink((level, message) => this.push(level, message));
-    tx.setAttachmentSink((image3, ts) => this.queueAttachment(image3, ts));
-    const checkCanceled = () => this.checkCanceled();
-    tx.setStepGuard(checkCanceled);
-    const eachSink = {
-      report: (status, message, payload, id, image3) => this.addItem(status, message, payload, id, image3),
-      startStep: (op, description) => tx.start(op, description),
-      stepScope: (step, fn) => tx.scope(step, fn),
-      declareTotal: (total) => {
-        if (this.progressTotal == null) this.setProgress(this.progressCurrent, total);
-      },
-      advance: () => this.setProgress(this.progressCurrent + 1, this.progressTotal),
-      checkCanceled,
-      isAborted: () => this.abortController.signal.aborted,
-      logError: (message) => this.log("error", message),
-      flush: () => this.flush()
-    };
-    const items = {
-      add: (item) => {
-        checkCanceled();
-        this.addItem(item.status, item.message, item.payload, item.id, item.image);
-      },
-      succeeded: (payload, options) => {
-        checkCanceled();
-        this.addItem("succeeded", void 0, payload, options?.id, options?.image);
-      },
-      failed: (message, payload, options) => {
-        checkCanceled();
-        this.addItem("failed", message, payload, options?.id, options?.image);
-      },
-      occurrence: (message, payload, options) => {
-        checkCanceled();
-        this.addItem("occurrence", message, payload, options?.id, options?.image);
-      },
-      each: (list, handler, options = {}) => eachItem(list, handler, options, eachSink)
-    };
-    const progress = Object.defineProperties(
-      {
-        total: (total) => {
-          checkCanceled();
-          this.setProgress(this.progressCurrent, total);
-        },
-        advance: (count = 1) => {
-          checkCanceled();
-          this.setProgress(this.progressCurrent + count, this.progressTotal);
-        },
-        set: (current, total) => {
-          checkCanceled();
-          this.setProgress(current, total ?? this.progressTotal);
-        }
-      },
-      {
-        current: { enumerable: true, get: () => this.progressCurrent },
-        snapshot: {
-          enumerable: true,
-          get: () => this.progressTotal == null ? null : { current: this.progressCurrent, total: this.progressTotal }
-        }
-      }
-      // defineProperties não tipa os getters adicionados — a interface é a fonte de verdade
-    );
-    const signal = this.abortController.signal;
-    const sleep2 = (ms) => cancelableSleep(ms, signal);
-    this.fileStore = new RunFileStore({ api, runId, params, signal, warn: (message) => this.log("warning", message) });
-    this.context = {
-      runId,
-      params,
-      log,
-      items,
-      progress,
-      files: this.fileStore.files,
-      step: async (name, fn, options) => {
-        const root = tx.currentStep() === void 0;
-        try {
-          return await tx.step(name, fn, { ...options, signal, wait: sleep2, warn: (message) => this.log("warning", message) });
-        } finally {
-          if (options?.flush !== false && root && !signal.aborted) await this.flush();
-        }
-      },
-      flush: (timeoutMs) => this.flush(timeoutMs),
-      signal,
-      throwIfCanceled: checkCanceled,
-      sleep: sleep2,
-      retry: (fn, options) => retryWithBackoff(fn, { ...options, signal, wait: sleep2 })
-    };
-  }
-  api;
-  runId;
-  logger;
-  tx;
-  context;
-  buffer = [];
-  dead = false;
-  chain = Promise.resolve();
-  pendingUpdates = 0;
-  timer;
-  watchTimer;
-  abortController = new AbortController();
-  flushIntervalMs;
-  cancelCheckIntervalMs;
-  // Itens de execução vivem FORA de `this.chain` (status/liveness não pode ficar
-  // atrás de milhares de itens), mas têm cadeia própria serializada — ordem de
-  // envio preservada e sem lotes sobrepostos.
-  itemsBuffer = [];
-  itemsChain = Promise.resolve();
-  itemsTimer;
-  itemSeq = 0;
-  /** Servidor sem o recurso (404) — para de tentar (e de avisar) nesta run. */
-  itemsUnsupported = false;
-  /**
-   * Cota de itens por run do servidor (429, legado — hoje a api não tem teto de itens) —
-   * degrada com um aviso só.
-   */
-  itemsQuotaExceeded = false;
-  /**
-   * Armazenamento do plano cheio (402 `storage_limit`): o lote é descartado e o aviso sai
-   * uma vez por episódio. Os envios continuam — num agente `start()` o espaço pode ser
-   * liberado (ou o plano trocado) sem reiniciar; um lote aceito rearma o aviso.
-   */
-  itemsStorageFull = false;
-  /**
-   * Só o kill() do exit path fecha os itens — `dead` (run cancelada/finalizada no
-   * servidor) NÃO fecha: o servidor aceita itens de run terminal (trabalho já feito).
-   */
-  itemsClosed = false;
-  // Uploads de anexo vivem FORA de `this.chain`: a cadeia é um FIFO puro de
-  // status/logs e não pode ficar bloqueada esperando um binário subir.
-  pendingAttachments = /* @__PURE__ */ new Set();
-  attachmentCount = 0;
-  uploadSlots = MAX_CONCURRENT_UPLOADS;
-  uploadQueue = [];
-  /** Uma vez que a instalação recusa anexos, para de tentar (e de avisar) nesta run. */
-  attachmentsUnsupported = false;
-  // Progresso (ctx.progress): snapshot absoluto, enviado com throttle via piggyback
-  // em `enqueue()` — nunca gera tráfego próprio enquanto logs/heartbeat já fluem.
-  progressCurrent = 0;
-  progressTotal = null;
-  /** Snapshot ainda não entregue ao servidor. */
-  progressDirty = false;
-  progressTimer;
-  progressWarned = false;
-  /** Relógio do último eco `[hobots:progress]` no terminal (throttle do eco, não do wire). */
-  progressLastPrint = 0;
-  /** Arquivos do formulário desta run (`ctx.files`) — a pasta temporária é apagada no fim. */
-  fileStore;
-  /** Apaga as cópias de arquivo que ficaram na pasta temporária da run. Nunca lança. */
-  cleanupFiles() {
-    return this.fileStore.cleanup();
-  }
-  get isDead() {
-    return this.dead;
-  }
-  /** Lança `RunCanceled` se o signal desta run já disparou. */
-  checkCanceled() {
-    if (this.abortController.signal.aborted) throw runCanceledError();
-  }
-  /** Aborta o ctx.signal sem matar o reporter (timeout/shutdown ainda reportam o terminal). */
-  abort() {
-    this.stopCancelWatch();
-    if (!this.abortController.signal.aborted) this.abortController.abort();
+  // ── Metadados ─────────────────────────────────────────────────────────────
+  setStatus(status) {
+    this.status = status;
+    return this;
   }
+  // ── Encerramento ──────────────────────────────────────────────────────────
   /**
-   * Mata o reporter de vez: aborta o signal e suprime todo reporte futuro.
-   * Usado no exit path — depois que o agente reportou AgentTerminated por fora
-   * da fila, um handler zumbi não pode reenviar status por cima.
+   * Envia já as etapas raiz finalizadas (e todas as descendentes, fechando as que
+   * ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
+   * `event_id` novo, até 200 etapas cada) e as tira da memória. Etapas raiz ainda abertas
+   * ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
+   * ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
+   * Devolve quantas etapas foram enviadas (0 sem client, sem nada terminado ou depois do `finish()`).
    */
-  kill() {
-    this.abort();
-    this.dead = true;
-    this.clearFlushTimer();
-    this.clearProgressTimer();
-    this.buffer = [];
-    this.itemsClosed = true;
-    this.clearItemsTimer();
-    if (this.itemsBuffer.length > 0) {
-      this.logger.warn(`${this.itemsBuffer.length} item(ns) de execu\xE7\xE3o descartados (processo encerrando)`);
-      this.itemsBuffer = [];
+  flush() {
+    if (!this.client || this.finished) return 0;
+    const ready = /* @__PURE__ */ new Set();
+    for (const step of this.steps) {
+      if (step.parentStepId === this.stepId && step.endTimestamp) ready.add(step.stepId);
     }
-    const waiting = this.uploadQueue.splice(0, this.uploadQueue.length);
-    for (const resume of waiting) resume();
-  }
-  /**
-   * Drena o buffer pendente para o PATCH único do exit path (chame ANTES de kill,
-   * que descarta o buffer). Capado em um chunk — o exit path não tem retry nem fila,
-   * então preserva os logs mais recentes, os mais valiosos na morte do processo.
-   */
-  drainLogs() {
-    this.clearFlushTimer();
-    return this.takeLogs().slice(-MAX_LOGS_PER_PATCH);
-  }
-  /**
-   * Linha de log da run com eco no terminal. `image` (opcional) vira o anexo da linha:
-   * o id entra na entrada ANTES de qualquer I/O — é isso que mantém a ordem dos logs
-   * intacta e o handler livre da latência do upload. Devolve o id do anexo (quando houve
-   * imagem e ela não foi descartada) — o `captureException` o leva ao evento da issue.
-   */
-  log(level, message, image3) {
-    if (this.dead) return void 0;
-    const scrubbed = scrubSecrets(safeString(message));
-    const ts = nowISO();
-    const attachmentId = image3 === void 0 ? void 0 : this.queueAttachment(image3, ts);
-    printRunLog(level, attachmentId ? `${scrubbed} [imagem]` : scrubbed);
-    this.push(level, scrubbed, true, attachmentId ? [attachmentId] : void 0, ts);
-    return attachmentId;
-  }
-  /** Bufferiza uma entrada de log sem eco no terminal (cap, truncate, flush). */
-  push(level, message, alreadyScrubbed = false, attachments, ts = nowISO()) {
-    if (this.dead) return ts;
-    const scrubbed = alreadyScrubbed ? message : scrubSecrets(message);
-    this.buffer.push({
-      ts,
-      level,
-      message: truncate(scrubbed, MAX_LOG_MESSAGE_CHARS),
-      ...attachments && attachments.length > 0 ? { attachments: attachments.slice(0, WIRE_LIMITS.MAX_ATTACHMENTS_PER_LOG_ENTRY) } : {}
-    });
-    if (this.buffer.length >= FLUSH_AT_BUFFERED) {
-      this.flushLogs();
-    } else {
-      this.scheduleFlush();
+    if (ready.size === 0) return 0;
+    const batch = [];
+    const remaining = [];
+    for (const step of this.steps) {
+      if (ready.has(step.stepId) || ready.has(step.parentStepId)) {
+        ready.add(step.stepId);
+        batch.push(step);
+      } else {
+        remaining.push(step);
+      }
     }
-    return ts;
+    for (const step of batch) step._close();
+    this.steps.splice(0, this.steps.length, ...remaining);
+    for (let i = 0; i < batch.length; i += MAX_STEPS) {
+      const chunk = batch.slice(i, i + MAX_STEPS);
+      const startTimestamp = chunk.reduce((min, step) => step.startTimestamp < min ? step.startTimestamp : min, chunk[0].startTimestamp);
+      const status = chunk.some((step) => step.status === "error") ? "error" : "ok";
+      this.client.sendTransaction(this.payload(uuid4(), FLUSH_TRANSACTION_OP, status, startTimestamp, nowISO(), chunk));
+    }
+    return batch.length;
   }
-  scheduleFlush() {
-    if (this.timer) return;
-    this.timer = setTimeout(() => {
-      this.timer = void 0;
-      this.flushLogs();
-    }, this.flushIntervalMs);
-    unrefTimer(this.timer);
+  /** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
+  async drain(timeoutMs) {
+    await this.client?.flush(timeoutMs);
+  }
+  payload(eventId, op, status, startTimestamp, timestamp, steps) {
+    return {
+      event_id: eventId,
+      name: this.name,
+      op,
+      status,
+      start_timestamp: startTimestamp,
+      timestamp,
+      steps: steps.map((step) => step.toJSON()),
+      // sem tags próprias: o client mescla as do processo
+      tags: void 0,
+      run_id: this.runId
+    };
   }
-  clearFlushTimer() {
-    if (this.timer) {
-      clearTimeout(this.timer);
-      this.timer = void 0;
+  finish() {
+    if (this.finished) return;
+    this.finished = true;
+    for (const step of this.steps) step._close();
+    const endTimestamp = nowISO();
+    this.emit(
+      "transaction",
+      "finish",
+      this.op ? `${this.name} (${this.op})` : this.name,
+      this.startTimestamp,
+      endTimestamp,
+      this.status
+    );
+    if (!this.client) return;
+    const steps = this.steps;
+    let first = 0;
+    while (steps.length - first > MAX_STEPS) {
+      const chunk = steps.slice(first, first + MAX_STEPS);
+      const status = chunk.some((step) => step.status === "error") ? "error" : "ok";
+      this.client.sendTransaction(this.payload(uuid4(), FLUSH_TRANSACTION_OP, status, chunk[0].startTimestamp, endTimestamp, chunk));
+      first += MAX_STEPS;
     }
+    this.client.sendTransaction(this.payload(this.eventId, this.op, this.status, this.startTimestamp, endTimestamp, steps.slice(first)));
   }
-  takeLogs() {
-    return this.buffer.splice(0, this.buffer.length);
+};
+
+// src/tasks/each.ts
+var DEFAULT_ITEM_ID_FIELD = "id";
+var DEFAULT_EACH_RETRIES = 1;
+var ID_SEPARATOR = "|";
+function thrownMessage(error) {
+  if (error instanceof Error) return error.message || error.name;
+  return safeString(error);
+}
+var ItemHandle = class {
+  constructor(index, id, step, basePayload, sink) {
+    this.index = index;
+    this.step = step;
+    this.basePayload = basePayload;
+    this.sink = sink;
+    this.id = id ?? uuid4();
   }
-  /** Flush incremental: envia o buffer como status 'running' (em chunks). */
-  flushLogs() {
-    this.clearFlushTimer();
-    if (this.dead || this.buffer.length === 0) return;
-    const logs = this.buffer.splice(0, this.buffer.length);
-    for (let i = 0; i < logs.length; i += MAX_LOGS_PER_PATCH) {
-      this.enqueue({ status: "running", logs: logs.slice(i, i + MAX_LOGS_PER_PATCH) });
-    }
+  index;
+  step;
+  basePayload;
+  sink;
+  /** A identidade resolvida por `options.id` ou, sem ela, uma gerada — a mesma em todas as tentativas. */
+  id;
+  reported = false;
+  status;
+  attempt = 1;
+  succeeded(payload, options) {
+    this.record("succeeded", void 0, payload, options?.image);
   }
-  /**
-   * `hobots.flush()`: o bot decide quando entregar o que já fez — etapas raiz finalizadas
-   * viram transactions parciais da run, e itens, logs e progresso pendentes saem já, sem
-   * esperar o throttle. Aguarda a entrega com teto. Nunca lança (pode ir num `finally`).
-   */
-  async flush(timeoutMs = ITEMS_DRAIN_MS) {
-    this.tx.flush();
-    this.flushItems();
-    if (this.progressDirty) this.flushProgress();
-    else this.flushLogs();
-    await Promise.race([
-      Promise.all([this.itemsChain, this.chain, this.tx.drain(timeoutMs)]).catch(() => void 0),
-      new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
-    ]);
+  failed(message, payload, options) {
+    this.record("failed", message, payload, options?.image);
+    if (this.step && this.step.status !== "error") this.step._setStatus("error", message);
   }
-  /** Primeiro PATCH (claimed → running). Retorna false se a run já morreu (cancelada). */
-  async reportRunning() {
-    this.enqueue({ status: "running" });
-    await this.chain;
-    if (!this.dead) this.startCancelWatch();
-    return !this.dead;
+  occurrence(message, payload, options) {
+    this.record("occurrence", message, payload, options?.image);
+    if (this.step && this.step.status === "ok") this.step._setStatus("warning", message);
   }
-  reportSuccess() {
-    this.stopCancelWatch();
-    this.clearFlushTimer();
-    this.forceFinalProgress();
-    this.enqueue({ status: "succeeded", logs: this.takeLogsForTerminal() });
+  /** Nova tentativa: o desfecho da anterior não vale (o id é o mesmo, o último reporte vence). */
+  _nextAttempt(attempt) {
+    this.attempt = attempt;
+    this.reported = false;
+    this.status = void 0;
+    if (this.step && (this.step.status === "error" || this.step.status === "warning")) {
+      this.step._setStatus("ok");
+      this.step._deleteData("message");
+    }
   }
-  reportFailure(error) {
-    this.stopCancelWatch();
-    this.clearFlushTimer();
-    this.forceFinalProgress();
-    this.enqueue({ status: "failed", error, logs: this.takeLogsForTerminal() });
+  record(status, message, payload, image3) {
+    this.reported = true;
+    this.status = status;
+    const merged = { ...this.basePayload ?? {}, ...payload ?? {} };
+    this.sink.report(status, message, Object.keys(merged).length > 0 ? merged : void 0, this.id, image3);
   }
-  /**
-   * Esvazia o buffer para o PATCH terminal respeitando o teto de 100 logs por PATCH:
-   * o excedente sai antes, em PATCHes `running` na mesma cadeia (a ordem se mantém).
-   */
-  takeLogsForTerminal() {
-    let logs = this.takeLogs();
-    while (logs.length > MAX_LOGS_PER_PATCH) {
-      this.enqueue({ status: "running", logs: logs.slice(0, MAX_LOGS_PER_PATCH) });
-      logs = logs.slice(MAX_LOGS_PER_PATCH);
+};
+function field(element, name) {
+  if (typeof element !== "object" || element === null) return { present: false, value: void 0 };
+  const record = element;
+  return { present: name in record, value: record[name] };
+}
+function resolveId(spec, element, index, explicit) {
+  if (spec === null) return void 0;
+  let raw;
+  if (typeof spec === "function") {
+    raw = spec(element, index);
+  } else {
+    const fields = spec === void 0 ? [DEFAULT_ITEM_ID_FIELD] : typeof spec === "string" ? [spec] : spec;
+    const parts = [];
+    for (const name of fields) {
+      const { present, value } = field(element, name);
+      if (!present || value === null || value === void 0) {
+        if (explicit) {
+          throw new Error(
+            `items.each: elemento #${index + 1} n\xE3o tem o campo "${name}" informado em id \u2014 passe o nome certo, uma lista de campos ou uma fun\xE7\xE3o (elemento, \xEDndice) => id`
+          );
+        }
+        return void 0;
+      }
+      parts.push(safeString(value));
     }
-    return logs;
+    raw = parts.join(ID_SEPARATOR);
   }
-  // ── Progresso ────────────────────────────────────────────────────────────────
-  /** Valida, clampa e marca o snapshot como pendente; agenda flush só se nada mais vai sair. */
-  setProgress(current, total) {
-    if (this.dead) return;
-    if (total != null && (!Number.isInteger(total) || total < 1)) {
-      if (!this.progressWarned) {
-        this.progressWarned = true;
-        this.logger.warn(`ctx.progress: total inv\xE1lido (${String(total)}) \u2014 precisa ser inteiro >= 1; ignorado`);
-      }
-      return;
+  if (raw === null || raw === void 0) return void 0;
+  const text = safeString(raw);
+  return text.length > 0 ? text : void 0;
+}
+function knownLength(list) {
+  const length = list?.length;
+  return typeof length === "number" && Number.isInteger(length) && length >= 1 ? length : void 0;
+}
+function skippedMessage(count) {
+  if (count === 1) return "1 item pulado: j\xE1 conclu\xEDdo neste trabalho numa execu\xE7\xE3o anterior";
+  return `${count} itens pulados: j\xE1 conclu\xEDdos neste trabalho numa execu\xE7\xE3o anterior`;
+}
+async function eachItem(list, handler, options, sink) {
+  const result = { total: 0, succeeded: 0, failed: 0, occurrence: 0, skipped: 0 };
+  const requested = options.retries ?? DEFAULT_EACH_RETRIES;
+  const totalRetries = Number.isFinite(requested) ? Math.max(0, Math.floor(requested)) : DEFAULT_EACH_RETRIES;
+  const explicitId = options.id !== void 0;
+  const length = options.progress === false ? void 0 : knownLength(list);
+  if (length !== void 0) sink.declareTotal(length);
+  const done = options.skipDone === false ? void 0 : await sink.doneItemIds();
+  let index = 0;
+  for await (const element of list) {
+    sink.checkCanceled();
+    const id = resolveId(options.id, element, index, explicitId);
+    if (done?.size && id !== void 0 && done.has(id)) {
+      result.total += 1;
+      result.skipped += 1;
+      if (options.progress !== false) sink.advance();
+      index += 1;
+      continue;
     }
-    const safeCurrent = Number.isFinite(current) ? Math.max(0, Math.floor(current)) : this.progressCurrent;
-    const next = total == null ? safeCurrent : Math.min(safeCurrent, total);
-    const totalChanged = total !== this.progressTotal;
-    if (next === this.progressCurrent && !totalChanged) return;
-    this.progressCurrent = next;
-    this.progressTotal = total;
-    if (total == null) return;
-    const now = Date.now();
-    if (totalChanged || next >= total || now - this.progressLastPrint >= PROGRESS_PRINT_THROTTLE_MS) {
-      this.progressLastPrint = now;
-      printRunProgress(next, total);
+    const description = options.description?.(element, index) ?? id ?? `#${index + 1}`;
+    const step = sink.startStep(options.op ?? "item", description);
+    const handle = new ItemHandle(index, id, step, options.payload?.(element, index), sink);
+    const current = index;
+    let attempts = 0;
+    let lastFailure;
+    try {
+      await retryWithBackoff(
+        (attempt) => {
+          attempts = attempt;
+          if (attempt > 1) handle._nextAttempt(attempt);
+          return sink.stepScope(step, async () => handler(element, handle, current));
+        },
+        {
+          retries: totalRetries,
+          delayMs: (attempt) => resolveDelay(options.retryDelayMs, attempt, DEFAULT_STEP_RETRY_DELAY_MS),
+          // sem nova tentativa: ocorrência (regra de negócio), desfecho já registrado pelo
+          // handler (ele decidiu) ou run abortada (o erro é efeito do cancelamento)
+          shouldRetry: (error) => !isOccurrence(error) && !handle.reported && !sink.isAborted(),
+          wait: (ms) => sink.sleep(ms),
+          onRetry: (error, attempt, delayMs) => {
+            lastFailure = { error };
+            sink.logWarning(
+              `item ${description}: tentativa ${attempt}/${totalRetries + 1} falhou: ${truncate(errorReason(error), 500)} \u2014 nova tentativa em ${delayMs}ms`
+            );
+          }
+        }
+      );
+      if (!handle.reported) handle.succeeded();
+      if (step) {
+        noteAttempts(step, attempts);
+        if (lastFailure && step.status === "ok") {
+          step._setStatus("warning", `tentativa ${attempts - 1}/${totalRetries + 1} falhou: ${errorReason(lastFailure.error)}`);
+        }
+      }
+    } catch (error) {
+      if (isTerminalError(error) || sink.isAborted()) {
+        step?._setStatus("cancelled")._close();
+        throw error;
+      }
+      if (step) noteAttempts(step, attempts);
+      if (isOccurrence(error)) {
+        const occurrence = error;
+        if (!handle.reported) handle.occurrence(occurrence.message, occurrence.payload, { image: occurrence.image });
+      } else {
+        const message = thrownMessage(error);
+        if (!handle.reported) handle.failed(message);
+        step?._failed(error);
+        sink.logError(`item ${description} falhou: ${message}`);
+      }
     }
-    this.progressDirty = true;
-    if (this.progressTimer) return;
-    this.progressTimer = setTimeout(() => {
-      this.progressTimer = void 0;
-      this.flushProgress();
-    }, PROGRESS_FLUSH_MS);
-    unrefTimer(this.progressTimer);
+    step?._close();
+    if (options.progress !== false) sink.advance();
+    result.total += 1;
+    result[handle.status ?? "succeeded"] += 1;
+    index += 1;
+    if (options.flush !== false) await sink.flush();
   }
-  flushProgress() {
-    this.clearProgressTimer();
-    if (this.dead || !this.progressDirty) return;
-    if (this.buffer.length > 0) this.flushLogs();
-    else this.enqueue({ status: "running" });
+  if (result.skipped > 0) sink.logInfo(skippedMessage(result.skipped));
+  return result;
+}
+function noteAttempts(step, attempts) {
+  if (attempts > 1) step._setData("attempts", attempts);
+}
+
+// src/tasks/files.ts
+var LOCAL_FILES_DIR_ENV = "HOBOTS_LOCAL_FILES_DIR";
+var FILE_DOWNLOAD_IDLE_TIMEOUT_MS = 6e4;
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isFileRef(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const ref = value;
+  return typeof ref.id === "string" && typeof ref.name === "string" && typeof ref.size === "number" && typeof ref.contentType === "string" && (ref.storage === "s3" || ref.storage === "local");
+}
+function fileField(params, field2) {
+  if (!Object.prototype.hasOwnProperty.call(params, field2)) return void 0;
+  const value = params[field2];
+  if (isFileRef(value)) return value;
+  if (Array.isArray(value) && value.every(isFileRef)) return value;
+  return void 0;
+}
+function collectFileRefs(params) {
+  const refs = [];
+  for (const field2 of Object.keys(params)) {
+    const value = fileField(params, field2);
+    if (value !== void 0) refs.push(...Array.isArray(value) ? value : [value]);
   }
-  clearProgressTimer() {
-    if (this.progressTimer) {
-      clearTimeout(this.progressTimer);
-      this.progressTimer = void 0;
+  return refs;
+}
+function safeFileName(name, fallback) {
+  const cleaned = name.replace(/^.*[\\/]/, "").replace(/[\u0000-\u001f<>:"|?*]/g, "_").trim();
+  return cleaned === "" || cleaned === "." || cleaned === ".." ? fallback : cleaned;
+}
+function isInsideDir(root, candidate, sep) {
+  const base = root.endsWith(sep) ? root : root + sep;
+  return candidate.startsWith(base) && candidate.length > base.length;
+}
+function unavailableLocal(ref) {
+  return new Error(`arquivo "${ref.name}" enviado pelo Studio de outro computador ou j\xE1 consumido`);
+}
+function localRunPath(ref) {
+  if (!isLocalRun()) return void 0;
+  const path = ref.path;
+  return typeof path === "string" && path.trim() !== "" ? path : void 0;
+}
+function errorCode(error) {
+  return error?.code;
+}
+var RunFileStore = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.files = {
+      list: () => collectFileRefs(deps.params),
+      get: (field2) => fileField(deps.params, field2),
+      // async: erro de uso (campo sem arquivo, valor inválido) chega como Promise rejeitada, nunca síncrono
+      download: async (refOrField, options) => this.download(this.single(refOrField), options?.dest),
+      downloadAll: async (field2, options) => this.downloadAll(field2, options?.dest),
+      read: async (refOrField) => this.read(this.single(refOrField))
+    };
+  }
+  deps;
+  files;
+  tempDir;
+  /** Apaga a pasta temporária da execução (cópias que o bot não levou para `dest`). Nunca lança. */
+  async cleanup() {
+    const pending = this.tempDir;
+    this.tempDir = void 0;
+    if (!pending) return;
+    try {
+      const { rm } = await import("fs/promises");
+      await rm(await pending, { recursive: true, force: true });
+    } catch {
     }
   }
-  /** O PATCH terminal sempre leva o snapshot final (o app mostra "87/100" numa run que falhou). */
-  forceFinalProgress() {
-    this.clearProgressTimer();
-    this.progressDirty = this.progressTotal != null;
+  field(field2) {
+    const value = fileField(this.deps.params, field2);
+    if (value === void 0) throw new Error(`campo "${field2}" n\xE3o tem arquivo nos params`);
+    return value;
   }
-  /** Consome o snapshot pendente para pegar carona no próximo PATCH. */
-  takeProgress() {
-    if (!this.progressDirty || this.progressTotal == null) return void 0;
-    this.progressDirty = false;
-    return { current: this.progressCurrent, total: this.progressTotal };
+  single(refOrField) {
+    if (typeof refOrField === "string") {
+      const value = this.field(refOrField);
+      if (Array.isArray(value)) {
+        throw new Error(`campo "${refOrField}" tem v\xE1rios arquivos \u2014 use downloadAll("${refOrField}") ou passe um item da lista`);
+      }
+      return value;
+    }
+    if (!isFileRef(refOrField)) throw new TypeError("esperado um FileRef ou o nome de um campo de arquivo");
+    return refOrField;
   }
-  /**
-   * Heartbeat de cancelamento: enquanto o handler roda, um PATCH 'running' vazio
-   * periódico faz o servidor responder 409 se a run foi cancelada no app — o que
-   * mata o reporter e dispara ctx.signal, mesmo em handlers que nunca logam.
-   */
-  startCancelWatch() {
-    if (this.watchTimer) return;
-    this.watchTimer = setInterval(() => {
-      if (this.dead || this.pendingUpdates > 0 || this.buffer.length > 0) return;
-      this.enqueue({ status: "running" });
-    }, this.cancelCheckIntervalMs);
-    unrefTimer(this.watchTimer);
+  async downloadAll(field2, dest) {
+    const value = this.field(field2);
+    const refs = Array.isArray(value) ? value : [value];
+    const paths = [];
+    for (const ref of refs) paths.push(await this.download(ref, dest, true));
+    return paths;
   }
-  stopCancelWatch() {
-    if (this.watchTimer) {
-      clearInterval(this.watchTimer);
-      this.watchTimer = void 0;
+  async read(ref) {
+    const { readFile, rm } = await import("fs/promises");
+    const { dirname } = await import("path");
+    const path = await this.download(ref, void 0);
+    try {
+      return await readFile(path);
+    } finally {
+      await rm(dirname(path), { recursive: true, force: true });
     }
   }
-  /** Aguarda a fila de PATCHes esvaziar (chame depois do terminal). */
-  finalize() {
-    return this.chain;
+  async download(ref, dest, destIsDir = false) {
+    this.checkCanceled();
+    const target = await this.resolveTarget(ref, dest, destIsDir);
+    if (ref.storage === "local") await this.copyLocal(ref, target);
+    else await this.downloadS3(ref, target);
+    return target;
   }
-  // ── Itens de execução ────────────────────────────────────────────────────────
-  /**
-   * Bufferiza um item (síncrono — a chamada nunca espera rede). Diferente do PATCH
-   * de status, o servidor aceita itens mesmo com a run cancelada (trabalho já feito),
-   * então um reporter morto não descarta: só um kill() de exit path descarta.
-   */
-  addItem(status, message, payload, id, image3) {
-    if (this.itemsClosed || this.itemsUnsupported) return;
-    let scrubbedPayload;
-    if (payload) {
-      scrubbedPayload = scrubPayloadValue(payload, 0);
-      let serializedLength;
-      try {
-        serializedLength = JSON.stringify(scrubbedPayload).length;
-      } catch {
-      }
-      if (serializedLength === void 0 || serializedLength > MAX_ITEM_PAYLOAD_BYTES) {
-        this.logger.warn(
-          `payload do item descartado (${serializedLength === void 0 ? "n\xE3o serializ\xE1vel" : `${serializedLength} bytes > ${MAX_ITEM_PAYLOAD_BYTES}`}) \u2014 o item foi mantido`
-        );
-        scrubbedPayload = void 0;
-      }
-    }
-    const ts = nowISO();
-    const attachmentId = image3 === void 0 ? void 0 : this.queueAttachment(image3, ts);
-    this.itemsBuffer.push({
-      id: id ? truncate(String(id), 255) : uuid4(),
-      seq: this.itemSeq++,
-      status,
-      ...message ? { message: truncate(scrubSecrets(safeString(message)), MAX_ITEM_MESSAGE_CHARS) } : {},
-      ...scrubbedPayload ? { payload: scrubbedPayload } : {},
-      ts,
-      ...attachmentId ? { attachments: [attachmentId] } : {}
-    });
-    if (this.itemsBuffer.length >= ITEMS_FLUSH_AT_BUFFERED) {
-      this.flushItems();
-    } else {
-      this.scheduleItemsFlush();
-    }
+  checkCanceled() {
+    if (this.deps.signal.aborted) throw runCanceledError();
   }
-  scheduleItemsFlush() {
-    if (this.itemsTimer) return;
-    this.itemsTimer = setTimeout(() => {
-      this.itemsTimer = void 0;
-      this.flushItems();
-    }, this.flushIntervalMs);
-    unrefTimer(this.itemsTimer);
+  runTempDir() {
+    this.tempDir ??= (async () => {
+      const { mkdtemp } = await import("fs/promises");
+      const { tmpdir } = await import("os");
+      const { join } = await import("path");
+      return mkdtemp(join(tmpdir(), "hobots-files-"));
+    })();
+    return this.tempDir;
   }
-  clearItemsTimer() {
-    if (this.itemsTimer) {
-      clearTimeout(this.itemsTimer);
-      this.itemsTimer = void 0;
+  async resolveTarget(ref, dest, destIsDir) {
+    const { mkdir, mkdtemp, stat } = await import("fs/promises");
+    const { dirname, join, resolve: resolve2 } = await import("path");
+    const name = safeFileName(ref.name, "arquivo");
+    if (dest === void 0) {
+      return join(await mkdtemp(join(await this.runTempDir(), "f-")), name);
     }
-  }
-  /** Envia o buffer de itens em lotes serializados na cadeia própria. */
-  flushItems() {
-    this.clearItemsTimer();
-    if (this.itemsBuffer.length === 0 || this.itemsUnsupported) return;
-    const items = this.itemsBuffer.splice(0, this.itemsBuffer.length);
-    for (let i = 0; i < items.length; i += MAX_ITEMS_PER_REQUEST) {
-      const batch = items.slice(i, i + MAX_ITEMS_PER_REQUEST);
-      this.itemsChain = this.itemsChain.then(() => this.sendItems(batch));
+    const isDir = destIsDir || dest.endsWith("/") || dest.endsWith("\\") || (await stat(dest).catch(() => void 0))?.isDirectory() === true;
+    if (isDir) {
+      await mkdir(dest, { recursive: true });
+      return resolve2(dest, name);
     }
+    await mkdir(dirname(resolve2(dest)), { recursive: true });
+    return resolve2(dest);
   }
-  async sendItems(batch) {
-    if (this.itemsUnsupported) return;
+  /** storage 's3': URL pré-assinada → GET em streaming → confere o tamanho → só então DELETE. */
+  async downloadS3(ref, target) {
+    const { api, runId, signal } = this.deps;
+    let expected;
+    let url;
     try {
-      await this.api.createItems(this.runId, { items: batch });
-      this.itemsStorageFull = false;
+      const info = await api.requestFileDownload(runId, ref.id, signal);
+      expected = info.size >= 0 ? info.size : ref.size;
+      url = info.url;
     } catch (error) {
-      if (error instanceof TasksApiError && error.status === 404) {
-        this.itemsUnsupported = true;
-        this.logger.warn("itens de execu\xE7\xE3o n\xE3o s\xE3o suportados por este servidor Hobots \u2014 descartados");
-        return;
-      }
-      if (error instanceof TasksApiError && error.status === 429) {
-        if (!this.itemsQuotaExceeded) {
-          this.itemsQuotaExceeded = true;
-          this.log("warning", "itens descartados: limite de itens por execu\xE7\xE3o atingido no servidor");
+      throw this.translate(error, ref);
+    }
+    const { open, rename, rm } = await import("fs/promises");
+    const part = `${target}.part`;
+    const idleTimeoutMs = this.deps.idleTimeoutMs ?? FILE_DOWNLOAD_IDLE_TIMEOUT_MS;
+    const controller = new AbortController();
+    let timedOut = false;
+    let timer;
+    const arm = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, idleTimeoutMs);
+    };
+    const onCancel = () => controller.abort();
+    signal.addEventListener("abort", onCancel, { once: true });
+    try {
+      arm();
+      const response = await api.fetchFile(url, controller.signal);
+      const handle = await open(part, "w");
+      let written = 0;
+      try {
+        const reader = response.body?.getReader();
+        const stopReading = () => void reader?.cancel().catch(() => void 0);
+        controller.signal.addEventListener("abort", stopReading, { once: true });
+        for (; ; ) {
+          const chunk = reader ? await reader.read() : { done: true, value: void 0 };
+          if (chunk.done) break;
+          arm();
+          written += chunk.value.byteLength;
+          if (written > expected) {
+            stopReading();
+            break;
+          }
+          await handle.write(chunk.value);
         }
-        return;
+      } finally {
+        await handle.close();
       }
-      if (error instanceof TasksApiError && error.status === 402) {
-        if (!this.itemsStorageFull) {
-          this.itemsStorageFull = true;
-          this.log("warning", "itens descartados: armazenamento do plano cheio \u2014 libere espa\xE7o ou fa\xE7a upgrade em Plano e cobran\xE7a");
-        }
-        return;
+      if (written !== expected) {
+        throw new Error(`tamanho divergente no download de "${ref.name}": recebidos ${written} bytes, esperados ${expected}`);
       }
-      if (error instanceof TasksApiError) {
-        this.logger.error(`lote de ${batch.length} item(ns) rejeitado pelo servidor:`, error);
-        this.log("warning", `${batch.length} item(ns) descartado(s): envio rejeitado pelo servidor (HTTP ${error.status})`);
-        return;
+      await rename(part, target);
+    } catch (error) {
+      await rm(part, { force: true });
+      if (signal.aborted) throw runCanceledError();
+      if (timedOut) {
+        throw new Error(`download de "${ref.name}" parado h\xE1 ${idleTimeoutMs / 1e3}s \u2014 tente de novo`);
       }
-      this.itemsBuffer.unshift(...batch);
-      this.scheduleItemsFlush();
-      this.logger.error(`lote de ${batch.length} item(ns) n\xE3o enviado (devolvido ao buffer):`, error);
+      throw this.translate(error, ref);
+    } finally {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onCancel);
     }
-  }
-  /**
-   * Dreno final de itens antes do PATCH terminal (com teto): garante que os
-   * totalizadores estejam completos quando a run vira succeeded/failed. Como o
-   * servidor aceita itens tardios, perder a corrida aqui não perde dados.
-   */
-  async finalizeItems(timeoutMs = ITEMS_DRAIN_MS) {
-    this.flushItems();
-    await Promise.race([
-      this.itemsChain,
-      new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
-    ]);
-    if (this.itemsBuffer.length > 0 && !this.itemsUnsupported && !this.itemsQuotaExceeded) {
-      this.flushItems();
-      await Promise.race([
-        this.itemsChain,
-        new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
-      ]);
+    try {
+      await api.confirmFileDownload(runId, ref.id);
+    } catch (error) {
+      this.deps.warn(`arquivo "${ref.name}" baixado, mas a confirma\xE7\xE3o ao servidor falhou: ${String(error)}`);
     }
   }
-  // ── Anexos ───────────────────────────────────────────────────────────────────
   /**
-   * Pendura uma imagem num evento da run (log, item ou etapa): faz as checagens que não
-   * dependem de I/O (reporter morto, instalação sem anexos, cota), reserva o id e dispara
-   * o upload em segundo plano. Devolve o id — já referenciável pelo evento — ou undefined
-   * quando a imagem foi descartada (sempre com aviso no log da run). Nunca lança: todo
-   * caminho de erro do upload vira aviso. O hint `attachment` de `hobots.captureException`
-   * também cai aqui via `log()`.
+   * storage 'local': copia o único arquivo de `$HOBOTS_LOCAL_FILES_DIR/<id>/` e apaga a pasta de
+   * origem. No modo local, um FileRef com `path` copia direto desse caminho, sem apagar a origem.
    */
-  queueAttachment(imageIn, ts) {
-    if (this.dead) return void 0;
-    const image3 = toImageAttachment(imageIn);
-    if (this.attachmentsUnsupported) return void 0;
-    if (this.attachmentCount >= MAX_ATTACHMENTS_PER_RUN) {
-      if (this.attachmentCount === MAX_ATTACHMENTS_PER_RUN) {
-        this.attachmentCount++;
-        this.log("warning", `imagem descartada: limite de ${MAX_ATTACHMENTS_PER_RUN} por execu\xE7\xE3o atingido`);
+  async copyLocal(ref, target) {
+    const direct = localRunPath(ref);
+    if (direct !== void 0) {
+      await this.copyFromPath(ref, direct, target);
+      return;
+    }
+    const base = process.env[LOCAL_FILES_DIR_ENV];
+    if (!base) throw unavailableLocal(ref);
+    const { copyFile, readdir, rename, rm, stat } = await import("fs/promises");
+    const { join, resolve: resolve2, sep } = await import("path");
+    const root = resolve2(base);
+    const folder = resolve2(root, ref.id);
+    if (!isInsideDir(root, folder, sep) || !UUID_RE.test(ref.id)) {
+      throw new Error(`id de arquivo local inv\xE1lido: ${JSON.stringify(ref.id)}`);
+    }
+    let names;
+    try {
+      names = (await readdir(folder, { withFileTypes: true })).filter((entry) => entry.isFile()).map((entry) => entry.name);
+    } catch (error) {
+      if (errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR") throw unavailableLocal(ref);
+      throw error;
+    }
+    if (names.length === 0) throw unavailableLocal(ref);
+    if (names.length > 1) throw new Error(`pasta do arquivo "${ref.name}" tem ${names.length} arquivos \u2014 esperado 1`);
+    this.checkCanceled();
+    const part = `${target}.part`;
+    try {
+      await copyFile(join(folder, names[0]), part);
+      const { size } = await stat(part);
+      if (size !== ref.size) {
+        throw new Error(`tamanho divergente na c\xF3pia de "${ref.name}": copiados ${size} bytes, esperados ${ref.size}`);
       }
-      return void 0;
+      await rename(part, target);
+    } catch (error) {
+      await rm(part, { force: true });
+      throw error;
     }
-    this.attachmentCount++;
-    const id = uuid4();
-    const rawCaption = image3.caption !== void 0 ? safeString(image3.caption) : void 0;
-    const caption = rawCaption ? truncate(scrubSecrets(rawCaption), MAX_CAPTION_CHARS) : void 0;
-    const work = this.uploadAttachment(id, image3.input, { caption, logTs: ts, contentType: image3.contentType }).then(() => void 0).catch(() => void 0);
-    this.pendingAttachments.add(work);
-    void work.finally(() => this.pendingAttachments.delete(work));
-    return id;
+    await rm(folder, { recursive: true, force: true });
   }
-  /** Retorna o motivo da falha, ou undefined em sucesso. */
-  async uploadAttachment(id, image3, meta) {
-    let bytes;
+  /**
+   * Modo local: cópia do arquivo apontado por `path` (teste roda várias vezes — a fonte fica).
+   * Sem conferência de tamanho: o `size` do FileRef é informativo aqui.
+   */
+  async copyFromPath(ref, path, target) {
+    const { copyFile, rename, rm, stat } = await import("fs/promises");
+    const { resolve: resolve2 } = await import("path");
+    const source = resolve2(path);
+    const info = await stat(source).catch(() => void 0);
+    if (!info?.isFile()) throw new Error(`arquivo "${ref.name}" n\xE3o encontrado em ${path}`);
+    this.checkCanceled();
+    const part = `${target}.part`;
     try {
-      bytes = await toBytes(image3);
+      await copyFile(source, part);
+      await rename(part, target);
     } catch (error) {
-      this.log("warning", `imagem n\xE3o p\xF4de ser lida: ${String(error)}`);
-      return "read-failed";
+      await rm(part, { force: true });
+      throw error;
     }
-    const contentType = sniffContentType(bytes) ?? meta.contentType;
-    if (!contentType) {
-      this.log("warning", "imagem descartada: formato n\xE3o reconhecido (aceitos: PNG, JPEG, WEBP)");
-      return "unsupported-format";
+  }
+  translate(error, ref) {
+    if (this.deps.signal.aborted) return runCanceledError();
+    if (error instanceof TasksApiError && error.status === 410) {
+      return new TasksApiError(`arquivo "${ref.name}" j\xE1 baixado ou expirado`, 410);
     }
-    if (bytes.byteLength > MAX_ATTACHMENT_BYTES) {
-      this.log(
-        "warning",
-        `imagem descartada: ${Math.round(bytes.byteLength / 1024)} KB excede o limite de ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB`
-      );
-      return "too-large";
+    if (error instanceof TasksApiError && error.status === 404) {
+      return new TasksApiError(`arquivo "${ref.name}" n\xE3o encontrado nesta execu\xE7\xE3o`, 404);
     }
-    const dimensions = readPngDimensions(bytes);
-    const release = await this.acquireUploadSlot();
-    try {
-      if (this.abortController.signal.aborted || this.dead) return "canceled";
-      const created = await this.api.createAttachment(
-        this.runId,
-        {
-          id,
-          content_type: contentType,
-          size_bytes: bytes.byteLength,
-          log_ts: meta.logTs,
-          ...meta.caption ? { caption: meta.caption } : {},
-          ...dimensions ?? {}
+    return error;
+  }
+};
+
+// src/tasks/context.ts
+var LOG_LEVEL_COLOR = {
+  debug: "gray",
+  info: "cyan",
+  warning: "yellow",
+  error: "red",
+  success: "green"
+};
+function joinLogArgs(message, rest) {
+  if (rest.length === 0) return safeString(message);
+  return [message, ...rest].map(safeString).join(" ");
+}
+function splitLogArgs(message, rest) {
+  const args = [message, ...rest];
+  const last = args[args.length - 1];
+  if (!isImageAttachment(last)) return { text: joinLogArgs(message, rest) };
+  const text = args.slice(0, -1);
+  if (text.length === 0) return { text: last.caption !== void 0 ? safeString(last.caption) : "captura de tela", image: last };
+  return { text: joinLogArgs(text[0], text.slice(1)), image: last };
+}
+function printRunLog(level, message) {
+  const line = colorize(`[hobots] ${level.toUpperCase()}`, LOG_LEVEL_COLOR[level]);
+  const method2 = level === "warning" ? "warn" : level === "success" ? "info" : level;
+  console[method2](line, message);
+}
+var PROGRESS_LINE_PREFIX = "[hobots:progress]";
+var PROGRESS_PRINT_THROTTLE_MS = 250;
+function printRunProgress(current, total) {
+  console.log(`${PROGRESS_LINE_PREFIX} ${current}/${total}`);
+}
+function cancelableSleep(ms, signal) {
+  return new Promise((resolve2, reject) => {
+    if (signal.aborted) {
+      reject(runCanceledError());
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(runCanceledError());
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve2();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var DEFAULT_LOG_FLUSH_INTERVAL_MS = 2e3;
+var DEFAULT_CANCEL_CHECK_INTERVAL_MS = 5e3;
+var MIN_CANCEL_CHECK_INTERVAL_MS = 1e3;
+var MAX_CANCEL_CHECK_INTERVAL_MS = 15e3;
+var MAX_LOG_MESSAGE_CHARS = WIRE_LIMITS.MAX_LOG_MESSAGE_CHARS;
+var MAX_LOGS_PER_PATCH = WIRE_LIMITS.MAX_LOGS_PER_PATCH;
+var FLUSH_AT_BUFFERED = 20;
+var MAX_ITEMS_PER_REQUEST = WIRE_LIMITS.MAX_ITEMS_PER_REQUEST;
+var MAX_ITEMS_DONE_PER_PAGE = WIRE_LIMITS.MAX_ITEMS_DONE_PER_PAGE;
+var MAX_ITEM_MESSAGE_CHARS = WIRE_LIMITS.MAX_ITEM_MESSAGE_CHARS;
+var MAX_ITEM_PAYLOAD_BYTES = WIRE_LIMITS.MAX_ITEM_PAYLOAD_BYTES;
+var ITEMS_FLUSH_AT_BUFFERED = 100;
+var ITEMS_DRAIN_MS = 15e3;
+var PROGRESS_FLUSH_MS = 1e3;
+function scrubPayloadValue(value, depth) {
+  if (typeof value === "string") return scrubSecrets(value);
+  if (depth >= 4 || value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((entry) => scrubPayloadValue(entry, depth + 1));
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    out[key] = scrubPayloadValue(entry, depth + 1);
+  }
+  return out;
+}
+var RunReporter = class {
+  constructor(api, runId, logger, tx, flushIntervalMs, cancelCheckIntervalMs, params = {}) {
+    this.api = api;
+    this.runId = runId;
+    this.logger = logger;
+    this.tx = tx;
+    this.flushIntervalMs = flushIntervalMs ?? DEFAULT_LOG_FLUSH_INTERVAL_MS;
+    this.cancelCheckIntervalMs = Math.min(
+      MAX_CANCEL_CHECK_INTERVAL_MS,
+      Math.max(MIN_CANCEL_CHECK_INTERVAL_MS, cancelCheckIntervalMs ?? DEFAULT_CANCEL_CHECK_INTERVAL_MS)
+    );
+    const logAt = (level) => (message, ...rest) => {
+      const { text, image: image3 } = splitLogArgs(message, rest);
+      this.log(level, text, image3);
+    };
+    const log = {
+      debug: logAt("debug"),
+      info: logAt("info"),
+      warn: logAt("warning"),
+      error: logAt("error"),
+      success: logAt("success")
+    };
+    tx.setLifecycleSink((level, message) => this.push(level, message));
+    tx.setAttachmentSink((image3, ts) => this.queueAttachment(image3, ts));
+    const checkCanceled = () => this.checkCanceled();
+    tx.setStepGuard(checkCanceled);
+    const eachSink = {
+      report: (status, message, payload, id, image3) => this.addItem(status, message, payload, id, image3),
+      startStep: (op, description) => tx.start(op, description),
+      stepScope: (step, fn) => tx.scope(step, fn),
+      declareTotal: (total) => {
+        if (this.progressTotal == null) this.setProgress(this.progressCurrent, total);
+      },
+      advance: () => this.setProgress(this.progressCurrent + 1, this.progressTotal),
+      checkCanceled,
+      isAborted: () => this.abortController.signal.aborted,
+      logInfo: (message) => this.log("info", message),
+      logWarning: (message) => this.log("warning", message),
+      logError: (message) => this.log("error", message),
+      sleep: (ms) => cancelableSleep(ms, this.abortController.signal),
+      doneItemIds: () => this.listDoneItemIds(),
+      flush: () => this.flush()
+    };
+    const items = {
+      add: (item) => {
+        checkCanceled();
+        this.addItem(item.status, item.message, item.payload, item.id, item.image);
+      },
+      succeeded: (payload, options) => {
+        checkCanceled();
+        this.addItem("succeeded", void 0, payload, options?.id, options?.image);
+      },
+      failed: (message, payload, options) => {
+        checkCanceled();
+        this.addItem("failed", message, payload, options?.id, options?.image);
+      },
+      occurrence: (message, payload, options) => {
+        checkCanceled();
+        this.addItem("occurrence", message, payload, options?.id, options?.image);
+      },
+      each: (list, handler, options = {}) => eachItem(list, handler, options, eachSink)
+    };
+    const progress = Object.defineProperties(
+      {
+        total: (total) => {
+          checkCanceled();
+          this.setProgress(this.progressCurrent, total);
+        },
+        advance: (count = 1) => {
+          checkCanceled();
+          this.setProgress(this.progressCurrent + count, this.progressTotal);
         },
-        this.abortController.signal
-      );
-      await this.api.uploadAttachment(created.upload_url, created.headers, bytes, this.abortController.signal);
-      await this.api.confirmAttachment(this.runId, id, { status: "uploaded", size_bytes: bytes.byteLength, ...dimensions ?? {} }).catch(() => {
-      });
-      return void 0;
-    } catch (error) {
-      if (this.isUnsupported(error)) {
-        this.attachmentsUnsupported = true;
-        this.log("warning", "anexos n\xE3o est\xE3o habilitados nesta instala\xE7\xE3o do Hobots \u2014 imagem n\xE3o enviada");
-        return "unsupported";
-      }
-      if (error instanceof TasksApiError && error.status === 429) {
-        this.log("warning", "imagem descartada: limite de anexos por execu\xE7\xE3o atingido no servidor");
-        return "quota";
+        set: (current, total) => {
+          checkCanceled();
+          this.setProgress(current, total ?? this.progressTotal);
+        }
+      },
+      {
+        current: { enumerable: true, get: () => this.progressCurrent },
+        snapshot: {
+          enumerable: true,
+          get: () => this.progressTotal == null ? null : { current: this.progressCurrent, total: this.progressTotal }
+        }
       }
-      if (this.abortController.signal.aborted) return "canceled";
-      this.log("warning", `falha ao enviar a imagem: ${String(error)}`);
-      void this.api.confirmAttachment(this.runId, id, { status: "failed" }).catch(() => {
-      });
-      return "upload-failed";
-    } finally {
-      release();
-    }
-  }
-  /** 404 = API anterior ao recurso; 501/503 = instalação sem S3 configurado. */
-  isUnsupported(error) {
-    return error instanceof TasksApiError && (error.status === 404 || error.status === 501 || error.status === 503);
-  }
-  /** Semáforo simples: no máximo MAX_CONCURRENT_UPLOADS binários em voo por run. */
-  acquireUploadSlot() {
-    const release = () => {
-      const next = this.uploadQueue.shift();
-      if (next) next();
-      else this.uploadSlots++;
+      // defineProperties não tipa os getters adicionados — a interface é a fonte de verdade
+    );
+    const signal = this.abortController.signal;
+    const sleep2 = (ms) => cancelableSleep(ms, signal);
+    this.fileStore = new RunFileStore({ api, runId, params, signal, warn: (message) => this.log("warning", message) });
+    this.context = {
+      runId,
+      params,
+      log,
+      items,
+      progress,
+      files: this.fileStore.files,
+      step: async (name, fn, options) => {
+        const root = tx.currentStep() === void 0;
+        try {
+          return await tx.step(name, fn, { ...options, signal, wait: sleep2, warn: (message) => this.log("warning", message) });
+        } finally {
+          if (options?.flush !== false && root && !signal.aborted) await this.flush();
+        }
+      },
+      flush: (timeoutMs) => this.flush(timeoutMs),
+      signal,
+      throwIfCanceled: checkCanceled,
+      sleep: sleep2,
+      retry: (fn, options) => retryWithBackoff(fn, { ...options, signal, wait: sleep2 })
     };
-    if (this.uploadSlots > 0) {
-      this.uploadSlots--;
-      return Promise.resolve(release);
-    }
-    return new Promise((resolve2) => {
-      this.uploadQueue.push(() => resolve2(release));
-    });
   }
+  api;
+  runId;
+  logger;
+  tx;
+  context;
+  buffer = [];
+  dead = false;
+  chain = Promise.resolve();
+  pendingUpdates = 0;
+  timer;
+  watchTimer;
+  abortController = new AbortController();
+  flushIntervalMs;
+  cancelCheckIntervalMs;
+  // Itens de execução vivem FORA de `this.chain` (status/liveness não pode ficar
+  // atrás de milhares de itens), mas têm cadeia própria serializada — ordem de
+  // envio preservada e sem lotes sobrepostos.
+  itemsBuffer = [];
+  itemsChain = Promise.resolve();
+  itemsTimer;
+  itemSeq = 0;
+  /** Servidor sem o recurso (404) — para de tentar (e de avisar) nesta run. */
+  itemsUnsupported = false;
   /**
-   * Espera os uploads pendentes antes do PATCH terminal, para a run não terminar
-   * exibindo miniaturas em "enviando…". Capado: um upload lento não segura a run.
+   * Cota de itens por run do servidor (429, legado — hoje a api não tem teto de itens) —
+   * degrada com um aviso só.
    */
-  async finalizeAttachments(timeoutMs = ATTACHMENT_DRAIN_MS) {
-    if (this.pendingAttachments.size === 0) return;
-    await Promise.race([
-      Promise.allSettled([...this.pendingAttachments]),
-      new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
-    ]);
-  }
-  enqueue(updateIn) {
-    if (this.dead) {
-      this.salvageLogs(updateIn.logs);
-      return;
-    }
-    this.clearProgressTimer();
-    const progress = this.takeProgress();
-    const update = progress ? { ...updateIn, progress } : updateIn;
-    this.pendingUpdates++;
-    this.chain = this.chain.then(async () => {
-      if (this.dead) {
-        this.salvageLogs(update.logs);
-        return;
-      }
-      const payload = update.logs && update.logs.length === 0 ? { ...update, logs: void 0 } : update;
-      try {
-        await this.api.updateRun(this.runId, payload);
-      } catch (error) {
-        if (error instanceof TasksApiError && (error.status === 409 || error.status === 404)) {
-          this.dead = true;
-          this.stopCancelWatch();
-          this.abort();
-          const pending = this.buffer.splice(0, this.buffer.length);
-          this.salvageLogs(pending);
-          this.logger.warn(
-            `run ${this.runId} cancelada/finalizada no servidor \u2014 status suprimido` + (pending.length > 0 ? `, ${pending.length} log(s) enviados como log tardio` : "")
-          );
-          return;
-        }
-        if (update.logs && update.logs.length > 0) {
-          this.buffer.unshift(...update.logs);
-          this.scheduleFlush();
-        }
-        if (update.progress && this.progressTotal != null) this.progressDirty = true;
-        this.logger.error(`update da run ${this.runId} perdido:`, error);
-      }
-    }).finally(() => {
-      this.pendingUpdates--;
-    });
-  }
+  itemsQuotaExceeded = false;
   /**
-   * Best-effort de log tardio: envia logs para uma run já terminal, fora da fila.
-   * O servidor anexa os logs mesmo respondendo 409; erros são engolidos — este é
-   * o último recurso, não um canal confiável.
+   * Armazenamento do plano cheio (402 `storage_limit`): o lote é descartado e o aviso sai
+   * uma vez por episódio. Os envios continuam — num agente `start()` o espaço pode ser
+   * liberado (ou o plano trocado) sem reiniciar; um lote aceito rearma o aviso.
    */
-  salvageLogs(logs) {
-    if (!logs || logs.length === 0) return;
-    for (let i = 0; i < logs.length; i += MAX_LOGS_PER_PATCH) {
-      void this.api.updateRunOnce(this.runId, { status: "running", logs: logs.slice(i, i + MAX_LOGS_PER_PATCH) }).catch(() => {
-      });
-    }
+  itemsStorageFull = false;
+  /**
+   * Só o kill() do exit path fecha os itens — `dead` (run cancelada/finalizada no
+   * servidor) NÃO fecha: o servidor aceita itens de run terminal (trabalho já feito).
+   */
+  itemsClosed = false;
+  // Uploads de anexo vivem FORA de `this.chain`: a cadeia é um FIFO puro de
+  // status/logs e não pode ficar bloqueada esperando um binário subir.
+  pendingAttachments = /* @__PURE__ */ new Set();
+  attachmentCount = 0;
+  uploadSlots = MAX_CONCURRENT_UPLOADS;
+  uploadQueue = [];
+  /** Uma vez que a instalação recusa anexos, para de tentar (e de avisar) nesta run. */
+  attachmentsUnsupported = false;
+  // Progresso (ctx.progress): snapshot absoluto, enviado com throttle via piggyback
+  // em `enqueue()` — nunca gera tráfego próprio enquanto logs/heartbeat já fluem.
+  progressCurrent = 0;
+  progressTotal = null;
+  /** Snapshot ainda não entregue ao servidor. */
+  progressDirty = false;
+  progressTimer;
+  progressWarned = false;
+  /** Relógio do último eco `[hobots:progress]` no terminal (throttle do eco, não do wire). */
+  progressLastPrint = 0;
+  /** Arquivos do formulário desta run (`ctx.files`) — a pasta temporária é apagada no fim. */
+  fileStore;
+  /** Apaga as cópias de arquivo que ficaram na pasta temporária da run. Nunca lança. */
+  cleanupFiles() {
+    return this.fileStore.cleanup();
   }
-};
-
-// src/tasks/run-context-store.ts
-var storage;
-var stepStorage;
-var initPromise;
-async function ensureStorage() {
-  if (storage || !isNode()) return;
-  initPromise ??= import("async_hooks").then(({ AsyncLocalStorage: ALS }) => {
-    storage = new ALS();
-    stepStorage = new ALS();
-  });
-  await initPromise;
-}
-async function runWithRunContext(store, fn) {
-  await ensureStorage();
-  return storage ? storage.run(store, fn) : fn();
-}
-function currentRunReporter() {
-  return storage?.getStore()?.reporter;
-}
-async function runWithStepScope(scope, fn) {
-  await ensureStorage();
-  return stepStorage ? stepStorage.run(scope, fn) : fn();
-}
-function currentStep(transaction) {
-  const scope = stepStorage?.getStore();
-  return scope?.transaction === transaction ? scope.step : void 0;
-}
-
-// src/transaction.ts
-var FLUSH_TRANSACTION_OP = "hobots.run.flush";
-var DEFAULT_STEP_RETRIES = 1;
-var DEFAULT_STEP_RETRY_DELAY_MS = 5e3;
-var MAX_STEP_MESSAGE_CHARS = 2e3;
-var MAX_BACKLOG = 100;
-function stepMessage(text) {
-  return clip(scrubSecrets(text), MAX_STEP_MESSAGE_CHARS);
-}
-function stepId() {
-  return uuid4().slice(0, 16);
-}
-function stepLabel(op, description) {
-  return [op, description].filter(Boolean).join(" \u2014 ") || "(sem nome)";
-}
-function errorText(error) {
-  if (error instanceof Error) return error.message || error.name;
-  return safeString(error);
-}
-function errorReason(error) {
-  return error instanceof Error ? `${error.name}: ${errorText(error)}` : errorText(error);
-}
-function levelForStatus(status) {
-  switch (status) {
-    case "warning":
-      return "warning";
-    case "error":
-      return "error";
-    case "cancelled":
-      return "warning";
-    default:
-      return "success";
+  get isDead() {
+    return this.dead;
   }
-}
-function colorForStatus(status) {
-  switch (status) {
-    case "warning":
-      return "yellow";
-    case "error":
-      return "red";
-    case "cancelled":
-      return "gray";
-    default:
-      return "green";
+  /** Lança `RunCanceled` se o signal desta run já disparou. */
+  checkCanceled() {
+    if (this.abortController.signal.aborted) throw runCanceledError();
   }
-}
-var Step = class {
-  constructor(transaction, parentStepId, op, description) {
-    this.transaction = transaction;
-    this.parentStepId = parentStepId;
-    this.op = op;
-    this.description = description;
+  /** Aborta o ctx.signal sem matar o reporter (timeout/shutdown ainda reportam o terminal). */
+  abort() {
+    this.stopCancelWatch();
+    if (!this.abortController.signal.aborted) this.abortController.abort();
   }
-  transaction;
-  parentStepId;
-  op;
-  description;
-  stepId = stepId();
-  startTimestamp = nowISO();
-  status = "ok";
-  endTimestamp;
-  _data;
-  // ── API do bot ────────────────────────────────────────────────────────────
-  warning(message, options) {
-    if (this.status !== "error") this._setStatus("warning", message);
-    if (options?.image !== void 0) this.attachImage(options.image);
-    return this;
+  /**
+   * Mata o reporter de vez: aborta o signal e suprime todo reporte futuro.
+   * Usado no exit path — depois que o agente reportou AgentTerminated por fora
+   * da fila, um handler zumbi não pode reenviar status por cima.
+   */
+  kill() {
+    this.abort();
+    this.dead = true;
+    this.clearFlushTimer();
+    this.clearProgressTimer();
+    this.buffer = [];
+    this.itemsClosed = true;
+    this.clearItemsTimer();
+    if (this.itemsBuffer.length > 0) {
+      this.logger.warn(`${this.itemsBuffer.length} item(ns) de execu\xE7\xE3o descartados (processo encerrando)`);
+      this.itemsBuffer = [];
+    }
+    const waiting = this.uploadQueue.splice(0, this.uploadQueue.length);
+    for (const resume of waiting) resume();
   }
-  image(image3) {
-    this.attachImage(image3);
-    return this;
+  /**
+   * Drena o buffer pendente para o PATCH único do exit path (chame ANTES de kill,
+   * que descarta o buffer). Capado em um chunk — o exit path não tem retry nem fila,
+   * então preserva os logs mais recentes, os mais valiosos na morte do processo.
+   */
+  drainLogs() {
+    this.clearFlushTimer();
+    return this.takeLogs().slice(-MAX_LOGS_PER_PATCH);
   }
-  data(key, value) {
-    if (key === "attachments") return this;
-    this._setData(key, value);
-    return this;
+  /**
+   * Linha de log da run com eco no terminal. `image` (opcional) vira o anexo da linha:
+   * o id entra na entrada ANTES de qualquer I/O — é isso que mantém a ordem dos logs
+   * intacta e o handler livre da latência do upload. Devolve o id do anexo (quando houve
+   * imagem e ela não foi descartada) — o `captureException` o leva ao evento da issue.
+   */
+  log(level, message, image3) {
+    if (this.dead) return void 0;
+    const scrubbed = scrubSecrets(safeString(message));
+    const ts = nowISO();
+    const attachmentId = image3 === void 0 ? void 0 : this.queueAttachment(image3, ts);
+    printRunLog(level, attachmentId ? `${scrubbed} [imagem]` : scrubbed);
+    this.push(level, scrubbed, true, attachmentId ? [attachmentId] : void 0, ts);
+    return attachmentId;
   }
-  // ── Internos (chamados pelo SDK) ──────────────────────────────────────────
-  /** `data` da etapa como vai no wire (undefined quando vazio). */
-  get payload() {
-    return this._data;
+  /** Bufferiza uma entrada de log sem eco no terminal (cap, truncate, flush). */
+  push(level, message, alreadyScrubbed = false, attachments, ts = nowISO()) {
+    if (this.dead) return ts;
+    const scrubbed = alreadyScrubbed ? message : scrubSecrets(message);
+    this.buffer.push({
+      ts,
+      level,
+      message: truncate(scrubbed, MAX_LOG_MESSAGE_CHARS),
+      ...attachments && attachments.length > 0 ? { attachments: attachments.slice(0, WIRE_LIMITS.MAX_ATTACHMENTS_PER_LOG_ENTRY) } : {}
+    });
+    if (this.buffer.length >= FLUSH_AT_BUFFERED) {
+      this.flushLogs();
+    } else {
+      this.scheduleFlush();
+    }
+    return ts;
   }
-  _setStatus(status, message) {
-    this.status = status;
-    if (message) this._setData("message", stepMessage(safeString(message)));
-    return this;
+  scheduleFlush() {
+    if (this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = void 0;
+      this.flushLogs();
+    }, this.flushIntervalMs);
+    unrefTimer(this.timer);
+  }
+  clearFlushTimer() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = void 0;
+    }
+  }
+  takeLogs() {
+    return this.buffer.splice(0, this.buffer.length);
+  }
+  /** Flush incremental: envia o buffer como status 'running' (em chunks). */
+  flushLogs() {
+    this.clearFlushTimer();
+    if (this.dead || this.buffer.length === 0) return;
+    const logs = this.buffer.splice(0, this.buffer.length);
+    for (let i = 0; i < logs.length; i += MAX_LOGS_PER_PATCH) {
+      this.enqueue({ status: "running", logs: logs.slice(i, i + MAX_LOGS_PER_PATCH) });
+    }
   }
   /**
-   * Marca `error` guardando `{ type, message }` em `data.error` e fecha a etapa. Aceita qualquer
-   * valor lançado; `message` sobrescreve a mensagem do erro. Numa etapa já fechada não faz nada.
+   * `hobots.flush()`: o bot decide quando entregar o que já fez — etapas raiz finalizadas
+   * viram transactions parciais da run, e itens, logs e progresso pendentes saem já, sem
+   * esperar o throttle. Aguarda a entrega com teto. Nunca lança (pode ir num `finally`).
    */
-  _failed(error, message) {
-    if (this.endTimestamp) return this;
-    this.status = "error";
-    const type = error instanceof Error ? error.name : typeof error === "object" && error !== null ? "Error" : void 0;
-    const raw = message ?? errorText(error);
-    this._setData("error", { ...type ? { type } : {}, message: stepMessage(safeString(raw)) });
-    this._close();
-    return this;
+  async flush(timeoutMs = ITEMS_DRAIN_MS) {
+    this.tx.flush();
+    this.flushItems();
+    if (this.progressDirty) this.flushProgress();
+    else this.flushLogs();
+    await Promise.race([
+      Promise.all([this.itemsChain, this.chain, this.tx.drain(timeoutMs)]).catch(() => void 0),
+      new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
+    ]);
   }
-  _setData(key, value) {
-    this._data = { ...this._data, [key]: value };
+  /** Primeiro PATCH (claimed → running). Retorna false se a run já morreu (cancelada). */
+  async reportRunning() {
+    this.enqueue({ status: "running" });
+    await this.chain;
+    if (!this.dead) this.startCancelWatch();
+    return !this.dead;
+  }
+  reportSuccess() {
+    this.stopCancelWatch();
+    this.clearFlushTimer();
+    this.forceFinalProgress();
+    this.enqueue({ status: "succeeded", logs: this.takeLogsForTerminal() });
+  }
+  reportFailure(error) {
+    this.stopCancelWatch();
+    this.clearFlushTimer();
+    this.forceFinalProgress();
+    this.enqueue({ status: "failed", error, logs: this.takeLogsForTerminal() });
   }
   /**
-   * Dispara o upload pela run (sink do RunReporter) e referencia o anexo em
-   * `data.attachments` (chave reservada; teto igual ao das linhas de log). Fora de uma
-   * run não há onde pendurar a imagem — descarta com aviso único.
+   * Esvazia o buffer para o PATCH terminal respeitando o teto de 100 logs por PATCH:
+   * o excedente sai antes, em PATCHes `running` na mesma cadeia (a ordem se mantém).
    */
-  attachImage(image3) {
-    const current = Array.isArray(this._data?.attachments) ? this._data.attachments : [];
-    if (current.length >= MAX_ATTACHMENTS_PER_LOG_ENTRY) return;
-    const id = this.transaction.attachImage(image3);
-    if (!id) return;
-    this._setData("attachments", [...current, id]);
+  takeLogsForTerminal() {
+    let logs = this.takeLogs();
+    while (logs.length > MAX_LOGS_PER_PATCH) {
+      this.enqueue({ status: "running", logs: logs.slice(0, MAX_LOGS_PER_PATCH) });
+      logs = logs.slice(MAX_LOGS_PER_PATCH);
+    }
+    return logs;
   }
-  /** Motivo registrado (warning/erro) — usado no log de FINISH. */
-  reason() {
-    const error = this._data?.error;
-    const text = typeof error?.message === "string" ? error.message : this._data?.message;
-    return typeof text === "string" && text ? text : void 0;
+  // ── Progresso ────────────────────────────────────────────────────────────────
+  /** Valida, clampa e marca o snapshot como pendente; agenda flush só se nada mais vai sair. */
+  setProgress(current, total) {
+    if (this.dead) return;
+    if (total != null && (!Number.isInteger(total) || total < 1)) {
+      if (!this.progressWarned) {
+        this.progressWarned = true;
+        this.logger.warn(`ctx.progress: total inv\xE1lido (${String(total)}) \u2014 precisa ser inteiro >= 1; ignorado`);
+      }
+      return;
+    }
+    const safeCurrent = Number.isFinite(current) ? Math.max(0, Math.floor(current)) : this.progressCurrent;
+    const next = total == null ? safeCurrent : Math.min(safeCurrent, total);
+    const totalChanged = total !== this.progressTotal;
+    if (next === this.progressCurrent && !totalChanged) return;
+    this.progressCurrent = next;
+    this.progressTotal = total;
+    if (total == null) return;
+    const now = Date.now();
+    if (totalChanged || next >= total || now - this.progressLastPrint >= PROGRESS_PRINT_THROTTLE_MS) {
+      this.progressLastPrint = now;
+      printRunProgress(next, total);
+    }
+    this.progressDirty = true;
+    if (this.progressTimer) return;
+    this.progressTimer = setTimeout(() => {
+      this.progressTimer = void 0;
+      this.flushProgress();
+    }, PROGRESS_FLUSH_MS);
+    unrefTimer(this.progressTimer);
   }
-  /** Fecha a etapa mantendo o status que estiver. Idempotente. */
-  _close() {
-    if (this.endTimestamp) return;
-    this.endTimestamp = nowISO();
-    this.transaction.emit(
-      "step",
-      "finish",
-      stepLabel(this.op, this.description),
-      this.startTimestamp,
-      this.endTimestamp,
-      this.status,
-      this.reason()
-    );
+  flushProgress() {
+    this.clearProgressTimer();
+    if (this.dead || !this.progressDirty) return;
+    if (this.buffer.length > 0) this.flushLogs();
+    else this.enqueue({ status: "running" });
+  }
+  clearProgressTimer() {
+    if (this.progressTimer) {
+      clearTimeout(this.progressTimer);
+      this.progressTimer = void 0;
+    }
   }
-  toJSON() {
-    return {
-      step_id: this.stepId,
-      ...this.parentStepId ? { parent_step_id: this.parentStepId } : {},
-      ...this.op ? { op: clip(this.op, MAX_STEP_OP_CHARS) } : {},
-      ...this.description ? { description: clip(this.description, MAX_STEP_DESCRIPTION_CHARS) } : {},
-      status: this.status,
-      start_timestamp: this.startTimestamp,
-      timestamp: this.endTimestamp ?? nowISO(),
-      ...this._data ? { data: this._data } : {}
-    };
+  /** O PATCH terminal sempre leva o snapshot final (o app mostra "87/100" numa run que falhou). */
+  forceFinalProgress() {
+    this.clearProgressTimer();
+    this.progressDirty = this.progressTotal != null;
   }
-};
-var Transaction = class {
-  constructor(client, name, op, runId, options = {}) {
-    this.client = client;
-    this.name = name;
-    this.op = op;
-    this.runId = runId;
-    this.echo = options.echo ?? false;
-    this.emit("transaction", "start", op ? `${name} (${op})` : name);
+  /** Consome o snapshot pendente para pegar carona no próximo PATCH. */
+  takeProgress() {
+    if (!this.progressDirty || this.progressTotal == null) return void 0;
+    this.progressDirty = false;
+    return { current: this.progressCurrent, total: this.progressTotal };
   }
-  client;
-  name;
-  op;
-  runId;
-  eventId = uuid4();
-  stepId = stepId();
-  startTimestamp = nowISO();
-  status = "ok";
-  steps = [];
-  finished = false;
-  lifecycleSink;
-  attachmentSink;
-  warnedNoAttachmentSink = false;
-  // instalado pelo RunReporter: abrir uma etapa é um ponto de parada cooperativo (lança RunCanceled)
-  stepGuard;
-  // modo local (sem client): o FINISH de cada etapa sai no terminal, como `[hobots:item]`
-  echo;
-  // eventos emitidos antes do sink existir (o START da transaction sai no construtor,
-  // antes do RunReporter conectar) — replay no setLifecycleSink
-  lifecycleBacklog = [];
-  // ── Lifecycle / eco ───────────────────────────────────────────────────────
   /**
-   * Registra o início/fim de uma etapa ou da transaction: espelha a linha no sink de
-   * lifecycle, se conectado (é assim que os eventos de performance aparecem nos logs da
-   * run no app), e ecoa no terminal com `debug: true` — ou, no modo local, só o FINISH das
-   * etapas (`[hobots:step] FINISH …`), para o Studio e o dev verem.
+   * Heartbeat de cancelamento: enquanto o handler roda, um PATCH 'running' vazio
+   * periódico faz o servidor responder 409 se a run foi cancelada no app — o que
+   * mata o reporter e dispara ctx.signal, mesmo em handlers que nunca logam.
    */
-  emit(kind, phase, label, startTs, endTs, status, reason) {
-    const durationMs = startTs && endTs ? new Date(endTs).getTime() - new Date(startTs).getTime() : void 0;
-    const suffix = (durationMs != null ? ` (${durationMs}ms)` : "") + (reason ? `: ${reason}` : "");
-    const localFinish = this.echo && kind === "step" && phase === "finish";
-    if (this.client?.debug || localFinish) {
-      const tag = colorize(`[hobots:${kind}] ${phase.toUpperCase()}`, phase === "finish" ? colorForStatus(status ?? "ok") : "cyan");
-      console.log(`${tag} ${label}${suffix}`);
-    }
-    const level = phase === "finish" ? levelForStatus(status ?? "ok") : "info";
-    const message = `[${kind}] ${phase.toUpperCase()} ${label}${suffix}`;
-    if (this.lifecycleSink) this.lifecycleSink(level, message);
-    else if (this.lifecycleBacklog.length < MAX_BACKLOG) this.lifecycleBacklog.push([level, message]);
+  startCancelWatch() {
+    if (this.watchTimer) return;
+    this.watchTimer = setInterval(() => {
+      if (this.dead || this.pendingUpdates > 0 || this.buffer.length > 0) return;
+      this.enqueue({ status: "running" });
+    }, this.cancelCheckIntervalMs);
+    unrefTimer(this.watchTimer);
   }
-  /** Conecta o espelho de lifecycle (RunReporter) e faz replay do backlog em ordem. */
-  setLifecycleSink(sink) {
-    this.lifecycleSink = sink;
-    const backlog = this.lifecycleBacklog;
-    this.lifecycleBacklog = [];
-    for (const [level, message] of backlog) sink(level, message);
+  stopCancelWatch() {
+    if (this.watchTimer) {
+      clearInterval(this.watchTimer);
+      this.watchTimer = void 0;
+    }
   }
-  /** Conecta o pipeline de anexos da run — é o que dá imagem às etapas. */
-  setAttachmentSink(sink) {
-    this.attachmentSink = sink;
+  /** Aguarda a fila de PATCHes esvaziar (chame depois do terminal). */
+  finalize() {
+    return this.chain;
   }
-  /** Imagem de uma etapa → id do anexo pela run; sem run, descarta com aviso único. */
-  attachImage(image3) {
-    if (this.attachmentSink) return this.attachmentSink(image3, nowISO());
-    if (!this.warnedNoAttachmentSink) {
-      this.warnedNoAttachmentSink = true;
-      console.warn("[hobots] imagem de etapa descartada \u2014 s\xF3 \xE9 suportada dentro de uma execu\xE7\xE3o");
+  // ── Itens de execução ────────────────────────────────────────────────────────
+  /**
+   * Bufferiza um item (síncrono — a chamada nunca espera rede). Diferente do PATCH
+   * de status, o servidor aceita itens mesmo com a run cancelada (trabalho já feito),
+   * então um reporter morto não descarta: só um kill() de exit path descarta.
+   */
+  addItem(status, message, payload, id, image3) {
+    if (this.itemsClosed || this.itemsUnsupported) return;
+    let scrubbedPayload;
+    if (payload) {
+      scrubbedPayload = scrubPayloadValue(payload, 0);
+      let serializedLength;
+      try {
+        serializedLength = JSON.stringify(scrubbedPayload).length;
+      } catch {
+      }
+      if (serializedLength === void 0 || serializedLength > MAX_ITEM_PAYLOAD_BYTES) {
+        this.logger.warn(
+          `payload do item descartado (${serializedLength === void 0 ? "n\xE3o serializ\xE1vel" : `${serializedLength} bytes > ${MAX_ITEM_PAYLOAD_BYTES}`}) \u2014 o item foi mantido`
+        );
+        scrubbedPayload = void 0;
+      }
+    }
+    const ts = nowISO();
+    const attachmentId = image3 === void 0 ? void 0 : this.queueAttachment(image3, ts);
+    this.itemsBuffer.push({
+      id: id ? truncate(String(id), 255) : uuid4(),
+      seq: this.itemSeq++,
+      status,
+      ...message ? { message: truncate(scrubSecrets(safeString(message)), MAX_ITEM_MESSAGE_CHARS) } : {},
+      ...scrubbedPayload ? { payload: scrubbedPayload } : {},
+      ts,
+      ...attachmentId ? { attachments: [attachmentId] } : {}
+    });
+    if (this.itemsBuffer.length >= ITEMS_FLUSH_AT_BUFFERED) {
+      this.flushItems();
+    } else {
+      this.scheduleItemsFlush();
     }
-    return void 0;
   }
-  // ── Etapas ────────────────────────────────────────────────────────────────
   /**
-   * Conecta a checagem de cancelamento chamada antes de cada etapa nova (inclusive antes de
-   * cada nova tentativa) — é assim que `hobots.step()` para uma run cancelada.
+   * Ids já concluídos (`succeeded`/`occurrence`) neste trabalho — a run e suas reexecuções.
+   * Pagina até o fim. undefined quando a consulta falha (servidor antigo, rede): o `each`
+   * avisa e processa tudo, nunca trava a run por isso.
    */
-  setStepGuard(guard) {
-    this.stepGuard = guard;
+  async listDoneItemIds() {
+    const ids = /* @__PURE__ */ new Set();
+    let cursor = null;
+    try {
+      do {
+        const page = await this.api.listDoneItems(this.runId, {
+          limit: MAX_ITEMS_DONE_PER_PAGE,
+          ...cursor ? { cursor } : {}
+        });
+        for (const id of page.ids) ids.add(id);
+        cursor = page.next;
+      } while (cursor);
+      return ids;
+    } catch (error) {
+      this.log("warning", `n\xE3o foi poss\xEDvel consultar os itens j\xE1 conclu\xEDdos deste trabalho \u2014 todos ser\xE3o processados (${thrownMessage(error)})`);
+      return void 0;
+    }
   }
-  /** A etapa aberta por `step()` (ou `items.each`) no contexto async atual, se houver. */
-  currentStep() {
-    return currentStep(this);
+  scheduleItemsFlush() {
+    if (this.itemsTimer) return;
+    this.itemsTimer = setTimeout(() => {
+      this.itemsTimer = void 0;
+      this.flushItems();
+    }, this.flushIntervalMs);
+    unrefTimer(this.itemsTimer);
   }
-  /** Faz de `step` a etapa corrente durante `fn` (filhas aninham nela). Sem etapa, só roda `fn`. */
-  scope(step, fn) {
-    if (!step) return fn();
-    return runWithStepScope({ transaction: this, step }, fn);
+  clearItemsTimer() {
+    if (this.itemsTimer) {
+      clearTimeout(this.itemsTimer);
+      this.itemsTimer = void 0;
+    }
   }
-  /** Abre uma etapa sob a corrente (ou direta da transaction). Interno: o bot usa `step()`. */
-  start(op, description) {
-    this.stepGuard?.();
-    const parent = this.currentStep();
-    const step = new Step(this, parent ? parent.stepId : this.stepId, op, description);
-    this.steps.push(step);
-    this.emit("step", "start", stepLabel(op, description));
-    return step;
+  /** Envia o buffer de itens em lotes serializados na cadeia própria. */
+  flushItems() {
+    this.clearItemsTimer();
+    if (this.itemsBuffer.length === 0 || this.itemsUnsupported) return;
+    const items = this.itemsBuffer.splice(0, this.itemsBuffer.length);
+    for (let i = 0; i < items.length; i += MAX_ITEMS_PER_REQUEST) {
+      const batch = items.slice(i, i + MAX_ITEMS_PER_REQUEST);
+      this.itemsChain = this.itemsChain.then(() => this.sendItems(batch));
+    }
+  }
+  async sendItems(batch) {
+    if (this.itemsUnsupported) return;
+    try {
+      await this.api.createItems(this.runId, { items: batch });
+      this.itemsStorageFull = false;
+    } catch (error) {
+      if (error instanceof TasksApiError && error.status === 404) {
+        this.itemsUnsupported = true;
+        this.logger.warn("itens de execu\xE7\xE3o n\xE3o s\xE3o suportados por este servidor Hobots \u2014 descartados");
+        return;
+      }
+      if (error instanceof TasksApiError && error.status === 429) {
+        if (!this.itemsQuotaExceeded) {
+          this.itemsQuotaExceeded = true;
+          this.log("warning", "itens descartados: limite de itens por execu\xE7\xE3o atingido no servidor");
+        }
+        return;
+      }
+      if (error instanceof TasksApiError && error.status === 402) {
+        if (!this.itemsStorageFull) {
+          this.itemsStorageFull = true;
+          this.log("warning", "itens descartados: armazenamento do plano cheio \u2014 libere espa\xE7o ou fa\xE7a upgrade em Plano e cobran\xE7a");
+        }
+        return;
+      }
+      if (error instanceof TasksApiError) {
+        this.logger.error(`lote de ${batch.length} item(ns) rejeitado pelo servidor:`, error);
+        this.log("warning", `${batch.length} item(ns) descartado(s): envio rejeitado pelo servidor (HTTP ${error.status})`);
+        return;
+      }
+      this.itemsBuffer.unshift(...batch);
+      this.scheduleItemsFlush();
+      this.logger.error(`lote de ${batch.length} item(ns) n\xE3o enviado (devolvido ao buffer):`, error);
+    }
+  }
+  /**
+   * Dreno final de itens antes do PATCH terminal (com teto): garante que os
+   * totalizadores estejam completos quando a run vira succeeded/failed. Como o
+   * servidor aceita itens tardios, perder a corrida aqui não perde dados.
+   */
+  async finalizeItems(timeoutMs = ITEMS_DRAIN_MS) {
+    this.flushItems();
+    await Promise.race([
+      this.itemsChain,
+      new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
+    ]);
+    if (this.itemsBuffer.length > 0 && !this.itemsUnsupported && !this.itemsQuotaExceeded) {
+      this.flushItems();
+      await Promise.race([
+        this.itemsChain,
+        new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
+      ]);
+    }
+  }
+  // ── Anexos ───────────────────────────────────────────────────────────────────
+  /**
+   * Pendura uma imagem num evento da run (log, item ou etapa): faz as checagens que não
+   * dependem de I/O (reporter morto, instalação sem anexos, cota), reserva o id e dispara
+   * o upload em segundo plano. Devolve o id — já referenciável pelo evento — ou undefined
+   * quando a imagem foi descartada (sempre com aviso no log da run). Nunca lança: todo
+   * caminho de erro do upload vira aviso. O hint `attachment` de `hobots.captureException`
+   * também cai aqui via `log()`.
+   */
+  queueAttachment(imageIn, ts) {
+    if (this.dead) return void 0;
+    const image3 = toImageAttachment(imageIn);
+    if (this.attachmentsUnsupported) return void 0;
+    if (this.attachmentCount >= MAX_ATTACHMENTS_PER_RUN) {
+      if (this.attachmentCount === MAX_ATTACHMENTS_PER_RUN) {
+        this.attachmentCount++;
+        this.log("warning", `imagem descartada: limite de ${MAX_ATTACHMENTS_PER_RUN} por execu\xE7\xE3o atingido`);
+      }
+      return void 0;
+    }
+    this.attachmentCount++;
+    const id = uuid4();
+    const rawCaption = image3.caption !== void 0 ? safeString(image3.caption) : void 0;
+    const caption = rawCaption ? truncate(scrubSecrets(rawCaption), MAX_CAPTION_CHARS) : void 0;
+    const work = this.uploadAttachment(id, image3.input, { caption, logTs: ts, contentType: image3.contentType }).then(() => void 0).catch(() => void 0);
+    this.pendingAttachments.add(work);
+    void work.finally(() => this.pendingAttachments.delete(work));
+    return id;
   }
-  /**
-   * Registra a etapa `name` executando `fn(etapa)` até dar certo ou esgotar `retries`
-   * tentativas extras (default 1), esperando `retryDelayMs` entre elas (default 5 000).
-   * Resolve com o retorno de `fn`.
-   *
-   * Uma etapa só no waterfall, cobrindo todas as tentativas: `data.attempts` quando houve
-   * mais de uma; `warning` com o motivo quando a última deu certo; `error` (e a exceção
-   * sobe) quando esgotou; `cancelled` em cancelamento/timeout, que nunca repetem.
-   */
-  async step(name, fn, options = {}) {
-    const requested = options.retries ?? DEFAULT_STEP_RETRIES;
-    const totalRetries = Number.isFinite(requested) ? Math.max(0, Math.floor(requested)) : DEFAULT_STEP_RETRIES;
-    const step = this.start(void 0, safeString(name));
-    let attempts = 0;
-    let lastFailure;
+  /** Retorna o motivo da falha, ou undefined em sucesso. */
+  async uploadAttachment(id, image3, meta) {
+    let bytes;
     try {
-      const result = await retryWithBackoff(
-        (attempt) => {
-          attempts = attempt;
-          return this.scope(step, async () => fn(step));
-        },
+      bytes = await toBytes(image3);
+    } catch (error) {
+      this.log("warning", `imagem n\xE3o p\xF4de ser lida: ${String(error)}`);
+      return "read-failed";
+    }
+    const contentType = sniffContentType(bytes) ?? meta.contentType;
+    if (!contentType) {
+      this.log("warning", "imagem descartada: formato n\xE3o reconhecido (aceitos: PNG, JPEG, WEBP)");
+      return "unsupported-format";
+    }
+    if (bytes.byteLength > MAX_ATTACHMENT_BYTES) {
+      this.log(
+        "warning",
+        `imagem descartada: ${Math.round(bytes.byteLength / 1024)} KB excede o limite de ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB`
+      );
+      return "too-large";
+    }
+    const dimensions = readPngDimensions(bytes);
+    const release = await this.acquireUploadSlot();
+    try {
+      if (this.abortController.signal.aborted || this.dead) return "canceled";
+      const created = await this.api.createAttachment(
+        this.runId,
         {
-          retries: totalRetries,
-          delayMs: (attempt) => resolveDelay(options.retryDelayMs, attempt, DEFAULT_STEP_RETRY_DELAY_MS),
-          signal: options.signal,
-          wait: options.wait,
-          onRetry: (error, attempt, delayMs) => {
-            lastFailure = { error };
-            options.warn?.(
-              `etapa "${step.description}": tentativa ${attempt}/${totalRetries + 1} falhou: ${truncate(errorReason(error), 500)} \u2014 nova tentativa em ${delayMs}ms`
-            );
-          }
-        }
+          id,
+          content_type: contentType,
+          size_bytes: bytes.byteLength,
+          log_ts: meta.logTs,
+          ...meta.caption ? { caption: meta.caption } : {},
+          ...dimensions ?? {}
+        },
+        this.abortController.signal
       );
-      this.noteAttempts(step, attempts);
-      if (lastFailure && step.status === "ok") {
-        step._setStatus("warning", `tentativa ${attempts - 1}/${totalRetries + 1} falhou: ${errorReason(lastFailure.error)}`);
-      }
-      step._close();
-      return result;
+      await this.api.uploadAttachment(created.upload_url, created.headers, bytes, this.abortController.signal);
+      await this.api.confirmAttachment(this.runId, id, { status: "uploaded", size_bytes: bytes.byteLength, ...dimensions ?? {} }).catch(() => {
+      });
+      return void 0;
     } catch (error) {
-      this.noteAttempts(step, attempts);
-      if (isTerminalError(error)) step._setStatus("cancelled")._close();
-      else step._failed(error);
-      throw error;
+      if (this.isUnsupported(error)) {
+        this.attachmentsUnsupported = true;
+        this.log("warning", "anexos n\xE3o est\xE3o habilitados nesta instala\xE7\xE3o do Hobots \u2014 imagem n\xE3o enviada");
+        return "unsupported";
+      }
+      if (error instanceof TasksApiError && error.status === 429) {
+        this.log("warning", "imagem descartada: limite de anexos por execu\xE7\xE3o atingido no servidor");
+        return "quota";
+      }
+      if (this.abortController.signal.aborted) return "canceled";
+      this.log("warning", `falha ao enviar a imagem: ${String(error)}`);
+      void this.api.confirmAttachment(this.runId, id, { status: "failed" }).catch(() => {
+      });
+      return "upload-failed";
+    } finally {
+      release();
     }
   }
-  noteAttempts(step, attempts) {
-    if (attempts > 1) step._setData("attempts", attempts);
+  /** 404 = API anterior ao recurso; 501/503 = instalação sem S3 configurado. */
+  isUnsupported(error) {
+    return error instanceof TasksApiError && (error.status === 404 || error.status === 501 || error.status === 503);
   }
-  // ── Metadados ─────────────────────────────────────────────────────────────
-  setStatus(status) {
-    this.status = status;
-    return this;
+  /** Semáforo simples: no máximo MAX_CONCURRENT_UPLOADS binários em voo por run. */
+  acquireUploadSlot() {
+    const release = () => {
+      const next = this.uploadQueue.shift();
+      if (next) next();
+      else this.uploadSlots++;
+    };
+    if (this.uploadSlots > 0) {
+      this.uploadSlots--;
+      return Promise.resolve(release);
+    }
+    return new Promise((resolve2) => {
+      this.uploadQueue.push(() => resolve2(release));
+    });
   }
-  // ── Encerramento ──────────────────────────────────────────────────────────
   /**
-   * Envia já as etapas raiz finalizadas (e todas as descendentes, fechando as que
-   * ficaram abertas) como transactions parciais da mesma run (`op` hobots.run.flush,
-   * `event_id` novo, até 200 etapas cada) e as tira da memória. Etapas raiz ainda abertas
-   * ficam para o próximo flush ou para o `finish()`. É assim que um agente sempre
-   * ligado (`start()`), cuja run não termina, entrega as etapas enquanto processa.
-   * Devolve quantas etapas foram enviadas (0 sem client, sem nada terminado ou depois do `finish()`).
+   * Espera os uploads pendentes antes do PATCH terminal, para a run não terminar
+   * exibindo miniaturas em "enviando…". Capado: um upload lento não segura a run.
    */
-  flush() {
-    if (!this.client || this.finished) return 0;
-    const ready = /* @__PURE__ */ new Set();
-    for (const step of this.steps) {
-      if (step.parentStepId === this.stepId && step.endTimestamp) ready.add(step.stepId);
+  async finalizeAttachments(timeoutMs = ATTACHMENT_DRAIN_MS) {
+    if (this.pendingAttachments.size === 0) return;
+    await Promise.race([
+      Promise.allSettled([...this.pendingAttachments]),
+      new Promise((resolve2) => unrefTimer(setTimeout(resolve2, timeoutMs)))
+    ]);
+  }
+  enqueue(updateIn) {
+    if (this.dead) {
+      this.salvageLogs(updateIn.logs);
+      return;
     }
-    if (ready.size === 0) return 0;
-    const batch = [];
-    const remaining = [];
-    for (const step of this.steps) {
-      if (ready.has(step.stepId) || ready.has(step.parentStepId)) {
-        ready.add(step.stepId);
-        batch.push(step);
-      } else {
-        remaining.push(step);
+    this.clearProgressTimer();
+    const progress = this.takeProgress();
+    const update = progress ? { ...updateIn, progress } : updateIn;
+    this.pendingUpdates++;
+    this.chain = this.chain.then(async () => {
+      if (this.dead) {
+        this.salvageLogs(update.logs);
+        return;
       }
-    }
-    for (const step of batch) step._close();
-    this.steps.splice(0, this.steps.length, ...remaining);
-    for (let i = 0; i < batch.length; i += MAX_STEPS) {
-      const chunk = batch.slice(i, i + MAX_STEPS);
-      const startTimestamp = chunk.reduce((min, step) => step.startTimestamp < min ? step.startTimestamp : min, chunk[0].startTimestamp);
-      const status = chunk.some((step) => step.status === "error") ? "error" : "ok";
-      this.client.sendTransaction(this.payload(uuid4(), FLUSH_TRANSACTION_OP, status, startTimestamp, nowISO(), chunk));
-    }
-    return batch.length;
-  }
-  /** Entrega já (com teto) o que está na fila do transport — as transactions parciais inclusive. */
-  async drain(timeoutMs) {
-    await this.client?.flush(timeoutMs);
-  }
-  payload(eventId, op, status, startTimestamp, timestamp, steps) {
-    return {
-      event_id: eventId,
-      name: this.name,
-      op,
-      status,
-      start_timestamp: startTimestamp,
-      timestamp,
-      steps: steps.map((step) => step.toJSON()),
-      // sem tags próprias: o client mescla as do processo
-      tags: void 0,
-      run_id: this.runId
-    };
+      const payload = update.logs && update.logs.length === 0 ? { ...update, logs: void 0 } : update;
+      try {
+        await this.api.updateRun(this.runId, payload);
+      } catch (error) {
+        if (error instanceof TasksApiError && (error.status === 409 || error.status === 404)) {
+          this.dead = true;
+          this.stopCancelWatch();
+          this.abort();
+          const pending = this.buffer.splice(0, this.buffer.length);
+          this.salvageLogs(pending);
+          this.logger.warn(
+            `run ${this.runId} cancelada/finalizada no servidor \u2014 status suprimido` + (pending.length > 0 ? `, ${pending.length} log(s) enviados como log tardio` : "")
+          );
+          return;
+        }
+        if (update.logs && update.logs.length > 0) {
+          this.buffer.unshift(...update.logs);
+          this.scheduleFlush();
+        }
+        if (update.progress && this.progressTotal != null) this.progressDirty = true;
+        this.logger.error(`update da run ${this.runId} perdido:`, error);
+      }
+    }).finally(() => {
+      this.pendingUpdates--;
+    });
   }
-  finish() {
-    if (this.finished) return;
-    this.finished = true;
-    for (const step of this.steps) step._close();
-    const endTimestamp = nowISO();
-    this.emit(
-      "transaction",
-      "finish",
-      this.op ? `${this.name} (${this.op})` : this.name,
-      this.startTimestamp,
-      endTimestamp,
-      this.status
-    );
-    if (!this.client) return;
-    const steps = this.steps;
-    let first = 0;
-    while (steps.length - first > MAX_STEPS) {
-      const chunk = steps.slice(first, first + MAX_STEPS);
-      const status = chunk.some((step) => step.status === "error") ? "error" : "ok";
-      this.client.sendTransaction(this.payload(uuid4(), FLUSH_TRANSACTION_OP, status, chunk[0].startTimestamp, endTimestamp, chunk));
-      first += MAX_STEPS;
+  /**
+   * Best-effort de log tardio: envia logs para uma run já terminal, fora da fila.
+   * O servidor anexa os logs mesmo respondendo 409; erros são engolidos — este é
+   * o último recurso, não um canal confiável.
+   */
+  salvageLogs(logs) {
+    if (!logs || logs.length === 0) return;
+    for (let i = 0; i < logs.length; i += MAX_LOGS_PER_PATCH) {
+      void this.api.updateRunOnce(this.runId, { status: "running", logs: logs.slice(i, i + MAX_LOGS_PER_PATCH) }).catch(() => {
+      });
     }
-    this.client.sendTransaction(this.payload(this.eventId, this.op, this.status, this.startTimestamp, endTimestamp, steps.slice(first)));
   }
 };
 
@@ -3415,6 +3589,10 @@ var LocalRunTransport = class {
     }
     return { accepted: request.items.length, duplicates: 0 };
   }
+  // modo local não tem trabalho anterior: nada a pular
+  async listDoneItems() {
+    return { ids: [], next: null };
+  }
   /** Totais por status — chame uma vez, no fim da run, antes da linha de conclusão. */
   printSummary() {
     const { succeeded, occurrence, failed } = this.counts;
@@ -3936,7 +4114,13 @@ var fallbackEachSink = {
   advance: noop,
   checkCanceled: noop,
   isAborted: () => false,
+  /* v8 ignore start -- fora de uma run não há consulta de concluídos, logo nunca há item pulado para anunciar */
+  logInfo: (message) => printRunLog("info", message),
+  /* v8 ignore stop */
+  logWarning: (message) => printRunLog("warning", message),
   logError: (message) => printRunLog("error", message),
+  sleep,
+  doneItemIds: () => Promise.resolve(void 0),
   flush: () => Promise.resolve()
 };
 var fallbackItems = {