@nmakarov/cli-toolkit 0.18.0 → 0.23.0

package/dist/tasks.js

@@ -1,4 +1,7 @@
-// src/utils/date-utils.ts
+// src/tasks/index.js
+import os3 from "os";
+
+// src/utils/date-utils.js
 function isTimestampFolder(folderName) {
   const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|\.\d{3}Z)$/;
   if (!isoRegex.test(folderName)) {
@@ -8,7 +11,7 @@ function isTimestampFolder(folderName) {
   return !isNaN(date.getTime()) && date.getTime() > 0;
 }
 
-// src/utils/fs-utils.ts
+// src/utils/fs-utils.js
 import fs from "fs";
 import path from "path";
 async function ensurePath(...pathParts) {
@@ -32,7 +35,7 @@ function getFileExtension(dataType) {
   }
 }
 
-// src/utils/os-utils.ts
+// src/utils/os-utils.js
 import fs2 from "fs";
 import path2 from "path";
 import { execSync } from "child_process";
@@ -61,7 +64,7 @@ function getFreeDiskSpace(targetPath) {
   }
 }
 
-// src/utils/format-utils.ts
+// src/utils/format-utils.js
 function bytesToHumanReadable(bytes) {
   if (bytes === 0) return "0 B";
   const k = 1024;
@@ -70,7 +73,7 @@ function bytesToHumanReadable(bytes) {
   return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
 }
 
-// src/utils/core-utils.ts
+// src/utils/core-utils.js
 function sleepMs(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -79,8 +82,82 @@ function toJsonColumn(value) {
   return JSON.stringify(value);
 }
 
-// src/tasks/taskUtils.ts
+// src/tasks/servicesRegistry.js
+import os from "os";
+
+// src/tasks/taskUtils.js
 import { randomUUID } from "crypto";
+
+// src/tasks/time-matcher.js
+var RANGES = ["0-59", "0-59", "0-23", "1-31", "1-12", "0-6"];
+function resolveAsterisks(field, range) {
+  return field.includes("*") ? field.replace("*", range) : field;
+}
+function resolveRanges(field) {
+  const regex = /(\d+)-(\d+)/;
+  let current = field;
+  while (true) {
+    const match = regex.exec(current);
+    if (!match) break;
+    const raw = match[0];
+    let first = Number(match[1]);
+    let last = Number(match[2]);
+    if (last < first) {
+      [first, last] = [last, first];
+    }
+    const values = [];
+    for (let i = first; i <= last; i += 1) {
+      values.push(i);
+    }
+    current = current.replace(raw, values.join(","));
+  }
+  return current;
+}
+function resolveSteps(field) {
+  const match = /^(.+)\/(\d+)$/.exec(field);
+  if (!match) return field;
+  const base = match[1];
+  const step = Number(match[2]);
+  if (!Number.isFinite(step) || step <= 0) return field;
+  return base.split(",").map((v) => Number(v)).filter((v) => Number.isFinite(v) && v % step === 0).join(",");
+}
+function convertPattern(pattern) {
+  const parts = pattern.trim().split(/\s+/);
+  if (parts.length !== 6) {
+    throw new Error(`Invalid schedule "${pattern}". Expected 6 fields: sec min hour day month weekday`);
+  }
+  return parts.map((field, idx) => resolveAsterisks(field, RANGES[idx])).map((field) => resolveRanges(field)).map((field) => resolveSteps(field));
+}
+function fieldMatches(field, value) {
+  const allowed = field.split(",").map((v) => Number(v));
+  return allowed.includes(value);
+}
+function matchesParsedPattern(parsed, date) {
+  return fieldMatches(parsed[0], date.getSeconds()) && fieldMatches(parsed[1], date.getMinutes()) && fieldMatches(parsed[2], date.getHours()) && fieldMatches(parsed[3], date.getDate()) && fieldMatches(parsed[4], date.getMonth() + 1) && fieldMatches(parsed[5], date.getDay());
+}
+function timeMatcher(pattern, date = /* @__PURE__ */ new Date()) {
+  const parsed = convertPattern(pattern);
+  return matchesParsedPattern(parsed, date);
+}
+var MS_PER_SECOND = 1e3;
+var DEFAULT_SEARCH_HORIZON_MS = 10 * 365 * 24 * 60 * 60 * MS_PER_SECOND;
+function nextTimeMatch(pattern, from = /* @__PURE__ */ new Date(), maxSearchMs = DEFAULT_SEARCH_HORIZON_MS) {
+  const parsed = convertPattern(pattern);
+  let t = Math.ceil((from.getTime() + 1) / MS_PER_SECOND) * MS_PER_SECOND;
+  const end = t + maxSearchMs;
+  while (t <= end) {
+    const date = new Date(t);
+    if (matchesParsedPattern(parsed, date)) {
+      return date;
+    }
+    t += MS_PER_SECOND;
+  }
+  throw new Error(
+    `nextTimeMatch: no match for "${pattern}" within ${maxSearchMs}ms after ${from.toISOString()}`
+  );
+}
+
+// src/tasks/taskUtils.js
 function getDb(context) {
   const db = context.db;
   if (!db) {
@@ -88,105 +165,117 @@ function getDb(context) {
   }
   return db;
 }
-function queueToTableNames(queue) {
-  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(queue)) {
-    throw new Error(`Invalid queue name "${queue}". Use letters, numbers, underscore only.`);
-  }
+function queueToTableNames(queueName) {
+  return {
+    tasksTable: queueName,
+    historyTable: `${queueName}_history`,
+    registryTable: `${queueName}_services_registry`
+  };
+}
+function defineTasksTable(t, db, tableNameForIndex) {
+  t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
+  t.timestamp("created_at").notNullable().defaultTo(db.fn.now());
+  t.timestamp("started_at");
+  t.timestamp("completed_at");
+  t.integer("priority").notNullable().defaultTo(50);
+  t.text("schedule");
+  t.timestamp("next_run_at").defaultTo(null);
+  t.timestamp("past_due").defaultTo(null);
+  t.text("name").notNullable();
+  t.text("opid");
+  t.json("params");
+  t.text("service_group");
+  t.integer("instance_number");
+  t.text("service_name");
+  t.text("server_name");
+  t.text("status").notNullable().defaultTo("idle");
+  t.timestamp("status_changed_at").defaultTo(null);
+  t.text("progress");
+  t.boolean("success");
+  t.json("results");
+  t.index(["service_group", "status", "priority", "created_at"], `${tableNameForIndex}_claim_idx`);
+  t.index(["service_group", "name"], `${tableNameForIndex}_group_name_idx`);
+}
+function taskHistoryInsertFromQueueRow(row, overrides) {
+  const { id, ...snapshot } = row;
+  void id;
   return {
-    tasksTable: queue,
-    historyTable: `${queue}_history`
+    ...snapshot,
+    ...overrides
   };
 }
 async function ensureTaskTables(context, options = {}) {
-  const queue = options.queue ?? "tasks";
+  const queueName = options.queueName ?? "tasks";
   const recreate = options.recreate ?? false;
   const db = getDb(context);
-  const { tasksTable, historyTable } = queueToTableNames(queue);
+  const { tasksTable, historyTable, registryTable } = queueToTableNames(queueName);
   const needsTasks = recreate ? true : !await db.tableExists(tasksTable);
   const needsHistory = recreate ? true : !await db.tableExists(historyTable);
+  const needsRegistry = recreate ? true : !await db.tableExists(registryTable);
   if (recreate) {
     await db.schema.dropTableIfExists(historyTable);
     await db.schema.dropTableIfExists(tasksTable);
+    await db.schema.dropTableIfExists(registryTable);
   }
   if (needsTasks) {
     await db.raw(`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`);
     await db.schema.createTable(tasksTable, (t) => {
-      t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
-      t.timestamp("created_at").notNullable().defaultTo(db.fn.now());
-      t.timestamp("started_at");
-      t.timestamp("completed_at");
-      t.integer("priority").notNullable().defaultTo(0);
-      t.text("schedule");
-      t.timestamp("past_due").defaultTo(null);
-      t.text("target").notNullable();
-      t.text("task").notNullable();
-      t.json("params");
-      t.text("opid");
-      t.timestamp("paused_at").defaultTo(null);
-      t.text("progress");
-      t.boolean("success");
-      t.json("results");
-    });
-    await db.schema.alterTable(tasksTable, (t) => {
-      t.index(["target", "started_at", "created_at"], `${tasksTable}_target_started_created_idx`);
-      t.index(["target", "past_due", "priority", "created_at"], `${tasksTable}_target_past_due_priority_created_idx`);
-      t.index(["target", "task"], `${tasksTable}_target_task_idx`);
-    });
-  }
-  const tasksHasOpid = await db.schema.hasColumn(tasksTable, "opid");
-  if (!tasksHasOpid) {
-    await db.schema.alterTable(tasksTable, (t) => {
-      t.text("opid");
-    });
-  }
-  const tasksHasPausedAt = await db.schema.hasColumn(tasksTable, "paused_at");
-  if (!tasksHasPausedAt) {
-    await db.schema.alterTable(tasksTable, (t) => {
-      t.timestamp("paused_at").defaultTo(null);
+      defineTasksTable(t, db, tasksTable);
     });
   }
   if (needsHistory) {
     await db.schema.createTable(historyTable, (t) => {
-      t.uuid("id").notNullable();
-      t.timestamp("created_at").notNullable();
-      t.timestamp("started_at");
-      t.timestamp("completed_at");
-      t.integer("priority").notNullable().defaultTo(0);
-      t.text("schedule");
-      t.timestamp("past_due").defaultTo(null);
-      t.text("target").notNullable();
-      t.text("task").notNullable();
-      t.json("params");
-      t.text("opid");
-      t.text("progress");
-      t.boolean("success");
-      t.json("results");
-    });
-    await db.schema.alterTable(historyTable, (t) => {
-      t.index(["target", "created_at"], `${historyTable}_target_created_idx`);
-      t.index(["task", "created_at"], `${historyTable}_task_created_idx`);
+      defineTasksTable(t, db, historyTable);
     });
   }
-  const historyHasOpid = await db.schema.hasColumn(historyTable, "opid");
-  if (!historyHasOpid) {
-    await db.schema.alterTable(historyTable, (t) => {
-      t.text("opid");
+  if (needsRegistry) {
+    await db.schema.createTable(registryTable, (t) => {
+      t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
+      t.text("queue_name").notNullable();
+      t.text("service_group").notNullable();
+      t.integer("instance_number").notNullable().defaultTo(1);
+      t.text("service_name").notNullable();
+      t.text("server_name").notNullable();
+      t.integer("pid");
+      t.json("metadata");
+      t.timestamp("created_at").notNullable().defaultTo(db.fn.now());
+      t.timestamp("last_seen_at").notNullable().defaultTo(db.fn.now());
+      t.unique(["queue_name", "service_name"], `${registryTable}_queue_name_service_name_uniq`);
+      t.index(["queue_name", "service_group", "last_seen_at"], `${registryTable}_queue_group_seen_idx`);
+      t.index(["queue_name", "last_seen_at"], `${registryTable}_queue_seen_idx`);
     });
   }
 }
 async function enqueueTask(context, options) {
   const db = getDb(context);
-  const queue = options.queue ?? "tasks";
-  const { tasksTable } = queueToTableNames(queue);
+  const queueName = options.queueName ?? "tasks";
+  const { tasksTable } = queueToTableNames(queueName);
   const id = randomUUID();
+  const name = options.name ?? options.task;
+  if (!name) {
+    throw new Error("enqueueTask: name (or task) is required");
+  }
+  const schedule = options.schedule?.trim() ? options.schedule : null;
+  let nextRunAt = null;
+  if (options.nextRunAt !== void 0) {
+    nextRunAt = options.nextRunAt == null ? null : new Date(options.nextRunAt);
+  } else if (schedule) {
+    nextRunAt = nextTimeMatch(schedule, /* @__PURE__ */ new Date());
+  }
   await db(tasksTable).insert({
     id,
-    target: options.target,
-    task: options.task,
+    name,
     params: toJsonColumn(options.params ?? null),
     opid: options.opid ?? null,
-    priority: options.priority ?? 0,
-    schedule: options.schedule ?? null
+    priority: options.priority ?? 50,
+    schedule,
+    next_run_at: nextRunAt,
+    service_group: options.serviceGroup ?? null,
+    instance_number: options.instanceNumber ?? null,
+    service_name: options.serviceName ?? null,
+    server_name: options.serverName ?? null,
+    status: "idle",
+    status_changed_at: db.fn.now()
   });
   return id;
 }
@@ -197,11 +286,261 @@ async function updateTaskProgress(context, tasksTable, taskId, progress) {
   });
 }
 
-// src/filedatabase/index.ts
+// src/tasks/servicesRegistry.js
+function getDb2(context) {
+  const db = context.db;
+  if (!db) {
+    throw new Error("Services registry requires context.db");
+  }
+  return db;
+}
+function parseMetadataColumn(value) {
+  if (!value) return {};
+  if (typeof value === "object" && !Array.isArray(value)) return value;
+  if (typeof value === "string") {
+    try {
+      const p = JSON.parse(value);
+      return p && typeof p === "object" && !Array.isArray(value) ? p : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+var DEFAULT_GROUP_MAX_INSTANCES = {
+  intake: 1,
+  harvest: 1,
+  harvester: 0,
+  loader: 0,
+  photos: 0,
+  photosprocessor: 0,
+  ingest: 0
+};
+function sanitizeNamePart(raw) {
+  const s = String(raw || "").trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return s.slice(0, 80) || "runner";
+}
+function resolveMaxInstances(serviceGroup, override) {
+  if (override !== void 0 && Number.isFinite(override)) {
+    return Math.max(0, Math.floor(Number(override)));
+  }
+  const g = serviceGroup.trim().toLowerCase();
+  return DEFAULT_GROUP_MAX_INSTANCES[g] ?? 0;
+}
+async function countAliveInGroup(db, registryTable, queueName, serviceGroup, staleMs, excludeRowId) {
+  const cutoff = new Date(Date.now() - staleMs);
+  let q = db(registryTable).where({ queue_name: queueName, service_group: serviceGroup }).where("last_seen_at", ">", cutoff);
+  if (excludeRowId) {
+    q = q.whereNot("id", excludeRowId);
+  }
+  const row = await q.count("id as count").first();
+  return Number(row?.count ?? 0);
+}
+async function getOccupiedInstanceSlots(db, registryTable, queueName, serviceGroup, staleMs) {
+  const cutoff = new Date(Date.now() - staleMs);
+  const rows = await db(registryTable).where({ queue_name: queueName, service_group: serviceGroup }).where("last_seen_at", ">", cutoff).select("instance_number");
+  const set = /* @__PURE__ */ new Set();
+  for (const r of rows) {
+    const n = Number(r.instance_number);
+    if (Number.isFinite(n) && n >= 1) set.add(Math.floor(n));
+  }
+  return set;
+}
+function isUniqueViolation(error) {
+  const code = error?.code ?? error?.errno;
+  return code === "23505" || String(error?.message || "").includes("duplicate key");
+}
+function buildMetadata(options) {
+  const base = options.metadata && typeof options.metadata === "object" ? { ...options.metadata } : {};
+  if (options.target) {
+    base.runnerTarget = options.target;
+  }
+  return toJsonColumn(Object.keys(base).length ? base : null);
+}
+function allocateInstanceNumber(occupied, explicit, maxSlots) {
+  if (explicit !== void 0 && explicit !== null && Number.isFinite(Number(explicit))) {
+    const e = Math.max(1, Math.floor(Number(explicit)));
+    if (occupied.has(e)) {
+      throw new Error(`[services-registry] instance slot ${e} is already occupied by an alive peer`);
+    }
+    if (maxSlots !== void 0 && maxSlots > 0 && e > maxSlots) {
+      throw new Error(`[services-registry] instance ${e} exceeds configured max slots ${maxSlots} for this group`);
+    }
+    return e;
+  }
+  const cap = maxSlots !== void 0 && maxSlots > 0 ? maxSlots : 1e4;
+  for (let n = 1; n <= cap; n++) {
+    if (!occupied.has(n)) return n;
+  }
+  throw new Error(`[services-registry] no free instance slot (searched 1..${cap})`);
+}
+function defaultServiceName(groupBase, hostBase, instanceNumber) {
+  return `${groupBase}-${hostBase}-${instanceNumber}`;
+}
+async function registerInServicesRegistry(context, options) {
+  const db = getDb2(context);
+  const registryTable = queueToTableNames(options.queueName).registryTable;
+  const serviceGroup = options.serviceGroup.trim();
+  if (!serviceGroup) {
+    throw new Error("registerInServicesRegistry: serviceGroup is required");
+  }
+  const serverName = os.hostname();
+  const pid = typeof process.pid === "number" ? process.pid : null;
+  const meta = buildMetadata(options);
+  const groupBase = sanitizeNamePart(serviceGroup);
+  const hostBase = sanitizeNamePart(serverName);
+  const maxAllowed = resolveMaxInstances(serviceGroup, options.groupMaxInstances);
+  const aliveCount = await countAliveInGroup(db, registryTable, options.queueName, serviceGroup, options.staleMs, void 0);
+  if (maxAllowed > 0 && aliveCount >= maxAllowed) {
+    const msg = `[services-registry] group limit reached for "${serviceGroup}": ${aliveCount} alive (max ${maxAllowed}, queue=${options.queueName}).`;
+    if (options.enforceMaxInstances) {
+      throw new Error(msg);
+    }
+    context.logger.warn?.(`${msg} Starting anyway (runnerEnforceMaxInstances=false).`);
+  }
+  const maxSlots = maxAllowed > 0 ? maxAllowed : void 0;
+  const cutoff = new Date(Date.now() - options.staleMs);
+  const MAX_ATTEMPTS = 8;
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const occupied = await getOccupiedInstanceSlots(db, registryTable, options.queueName, serviceGroup, options.staleMs);
+    const instanceNumber = allocateInstanceNumber(occupied, options.instanceNumber, maxSlots);
+    const serviceNameRaw = options.serviceName?.trim() ? sanitizeNamePart(options.serviceName.trim()) : defaultServiceName(groupBase, hostBase, instanceNumber);
+    const existing = await db(registryTable).where({ queue_name: options.queueName, service_name: serviceNameRaw }).first();
+    if (existing) {
+      const lastSeen = new Date(existing.last_seen_at);
+      const isAlive = !Number.isNaN(lastSeen.getTime()) && lastSeen > cutoff;
+      if (isAlive) {
+        if (options.serviceName?.trim()) {
+          throw new Error(
+            `[services-registry] service_name "${serviceNameRaw}" is already registered by an alive peer`
+          );
+        }
+        context.logger.warn?.(
+          `[services-registry] service_name "${serviceNameRaw}" already alive; retrying allocation (attempt ${attempt + 1})`
+        );
+        if (options.instanceNumber !== void 0 && options.instanceNumber !== null) {
+          throw new Error(
+            `[services-registry] instance slot ${instanceNumber} / name "${serviceNameRaw}" is already held by an alive peer`
+          );
+        }
+        await new Promise((r) => setTimeout(r, 50 + attempt * 30));
+        continue;
+      }
+      await db(registryTable).where({ id: existing.id }).update({
+        server_name: serverName,
+        pid,
+        metadata: meta,
+        service_group: serviceGroup,
+        instance_number: instanceNumber,
+        last_seen_at: db.fn.now()
+      });
+      const reg = {
+        serviceName: serviceNameRaw,
+        serviceGroup,
+        queueName: options.queueName,
+        target: options.target,
+        rowId: String(existing.id),
+        registryTable,
+        instanceNumber
+      };
+      context.servicesRegistry = reg;
+      context.runnerHeartbeat = reg;
+      context.logger.info?.(
+        `[services-registry] took over stale row name=${serviceNameRaw} instance=${instanceNumber} group=${serviceGroup} queue=${options.queueName}`
+      );
+      return reg;
+    }
+    try {
+      const rows = await db(registryTable).insert({
+        queue_name: options.queueName,
+        service_group: serviceGroup,
+        instance_number: instanceNumber,
+        service_name: serviceNameRaw,
+        server_name: serverName,
+        pid,
+        metadata: meta,
+        last_seen_at: db.fn.now(),
+        created_at: db.fn.now()
+      }).returning(["id", "service_name"]);
+      const row = Array.isArray(rows) ? rows[0] : rows;
+      let rowId = row && typeof row === "object" ? String(row.id ?? "") : "";
+      if (!rowId) {
+        const again = await db(registryTable).where({ queue_name: options.queueName, service_name: serviceNameRaw }).first();
+        rowId = again?.id != null ? String(again.id) : "";
+      }
+      if (!rowId) continue;
+      const regNew = {
+        serviceName: String(row?.service_name ?? serviceNameRaw),
+        serviceGroup,
+        queueName: options.queueName,
+        target: options.target,
+        rowId,
+        registryTable,
+        instanceNumber
+      };
+      context.servicesRegistry = regNew;
+      context.runnerHeartbeat = regNew;
+      context.logger.info?.(
+        `[services-registry] registered name=${regNew.serviceName} instance=${instanceNumber} group=${serviceGroup} queue=${options.queueName}`
+      );
+      return regNew;
+    } catch (error) {
+      if (!isUniqueViolation(error)) {
+        throw error;
+      }
+      context.logger.warn?.(`[services-registry] insert race on "${serviceNameRaw}", retrying (attempt ${attempt + 1})`);
+    }
+  }
+  throw new Error(
+    `[services-registry] could not allocate a registry row for group=${serviceGroup} queue=${options.queueName} after ${MAX_ATTEMPTS} attempts`
+  );
+}
+async function touchServicesRegistry(context, registration) {
+  const db = getDb2(context);
+  const serverName = os.hostname();
+  const pid = typeof process.pid === "number" ? process.pid : null;
+  await db(registration.registryTable).where({ id: registration.rowId }).update({
+    last_seen_at: db.fn.now(),
+    server_name: serverName,
+    pid
+  });
+}
+async function updateServicesRegistryMetadata(context, registration, patch) {
+  const db = getDb2(context);
+  const row = await db(registration.registryTable).where({ id: registration.rowId }).first();
+  const prev = parseMetadataColumn(row?.metadata);
+  const merged = { ...prev, ...patch };
+  await db(registration.registryTable).where({ id: registration.rowId }).update({
+    metadata: toJsonColumn(merged),
+    last_seen_at: db.fn.now()
+  });
+  context.logger.info?.(`[services-registry] metadata updated for ${registration.serviceName}`);
+}
+async function unregisterServicesRegistry(context, registration) {
+  const db = getDb2(context);
+  await db(registration.registryTable).where({ id: registration.rowId }).delete();
+  context.logger.info?.(`[services-registry] unregistered name=${registration.serviceName} id=${registration.rowId}`);
+}
+async function listServicesRegistry(context, options = { queueName: "tasks" }) {
+  const db = getDb2(context);
+  const staleMs = options.staleMs ?? 6e4;
+  const cutoff = new Date(Date.now() - staleMs);
+  const table = queueToTableNames(options.queueName).registryTable;
+  let q = db(table).where("last_seen_at", ">", cutoff).orderBy([{ column: "service_group", order: "asc" }, { column: "service_name", order: "asc" }]);
+  if (options.serviceGroup?.trim()) {
+    q = q.where({ service_group: options.serviceGroup.trim() });
+  }
+  return await q;
+}
+
+// src/tasks/taskLogs.js
+import path4 from "path";
+
+// src/filedatabase/index.js
 import fs3 from "fs";
 import path3 from "path";
 
-// src/filedatabase/serializers.ts
+// src/filedatabase/serializers.js
 function detectDataType(data) {
   if (Array.isArray(data)) {
     return "json-array";
@@ -233,7 +572,7 @@ function deserializeData(rawData, dataType) {
   }
 }
 
-// src/errors.ts
+// src/errors.js
 var FrameworkError = class extends Error {
   constructor(message) {
     super(message);
@@ -253,7 +592,7 @@ var FileDatabaseError = class extends FrameworkError {
   }
 };
 
-// src/filedatabase/index.ts
+// src/filedatabase/index.js
 var FileDatabase = class _FileDatabase {
   basePath;
   namespace;
@@ -339,7 +678,7 @@ var FileDatabase = class _FileDatabase {
     if (errors.length) {
       throw new FileDatabaseError(`[FileDatabase] ${errors.join("; ")}`);
     }
-    let parts = [this.basePath, this.namespace];
+    const parts = [this.basePath, this.namespace];
     if (this.tableName) {
       parts.push(...this.tableName.split("/"));
     }
@@ -832,14 +1171,17 @@ var FileDatabase = class _FileDatabase {
    * Prepare the instance for read or write operations
    * This discovers state and sets up internal members based on mode and current data
    */
-  async prepare({ write, read, version }) {
+  async prepare(options) {
+    const { write, read, version, deferInitialVersion } = options;
     if (write) {
       if (this.versioned) {
         if (this.currentVersion === null) {
-          await this.makeNewVersion();
-          this.metadata = this.getDefaultMetadata();
-          this.metadata.version = this.currentVersion;
-          this.makeNewFile();
+          if (!deferInitialVersion) {
+            await this.makeNewVersion();
+            this.metadata = this.getDefaultMetadata();
+            this.metadata.version = this.currentVersion;
+            this.makeNewFile();
+          }
         } else {
           if (!this.metadata.files.length) {
             this.metadata = await this.figureMetadata(this.currentVersion);
@@ -949,7 +1291,7 @@ var FileDatabase = class _FileDatabase {
     if (options.forceNewVersion && !this.versioned) {
       throw new FileDatabaseError("Cannot use forceNewVersion in non-versioned mode");
     }
-    await this.prepare({ write: true });
+    await this.prepare({ write: true, deferInitialVersion: !!(options.forceNewVersion && this.versioned) });
     const incomingDataType = detectDataType(data);
     this.metadata.dataType = incomingDataType;
     if (options.forceNewVersion) {
@@ -1243,7 +1585,7 @@ var FileDatabase = class _FileDatabase {
   }
 };
 
-// src/tasks/taskLogs.ts
+// src/tasks/taskLogs.js
 function getLogsState(context) {
   const holder = context;
   if (holder.__tasksLogsState) return holder.__tasksLogsState;
@@ -1296,6 +1638,96 @@ function getLogsState(context) {
   holder.__tasksLogsState = state;
   return state;
 }
+function ipcLogTargetKey(target) {
+  const bp = target.basePath ?? "";
+  const ns = target.namespace ?? "";
+  return `${bp}::${ns}::${target.tableName}`;
+}
+function ipcFileLogsTableNameForSourceResource(source, resource) {
+  const seg = (s) => {
+    const t = String(s).trim().replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+|_+$/g, "");
+    return t.length ? t : "x";
+  };
+  return `${seg(source)}/${seg(resource)}`;
+}
+async function readTaskIpcLogsSnapshot(context, options) {
+  const holder = context;
+  const basePath = holder.params?.get?.("tasksLogsBasePath") ?? "./data";
+  const namespace = holder.params?.get?.("tasksLogsNamespace") ?? "tasks-logs";
+  const tableName = ipcFileLogsTableNameForSourceResource(options.source, options.resource);
+  const tail = Math.max(1, Math.min(1e4, Number(options.tail) > 0 ? Number(options.tail) : 100));
+  const fd = new FileDatabase({
+    basePath,
+    namespace,
+    tableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: 30,
+    pageSize: 2e3,
+    logger: holder.logger
+  });
+  const versions = await fd.getVersions();
+  if (versions.length === 0) {
+    return { records: [], latestTs: null };
+  }
+  const latest = versions[versions.length - 1];
+  const raw = await fd.read({ version: latest });
+  const arr = Array.isArray(raw) ? raw : [];
+  let filtered = arr;
+  if (options.afterTs && String(options.afterTs).trim()) {
+    const cut = String(options.afterTs).trim();
+    filtered = arr.filter((r) => r && typeof r.ts === "string" && String(r.ts) > cut);
+  }
+  let latestTs = null;
+  for (const r of filtered) {
+    const ts = typeof r?.ts === "string" ? String(r.ts) : null;
+    if (ts && (!latestTs || ts > latestTs)) latestTs = ts;
+  }
+  const incremental = !!(options.afterTs && String(options.afterTs).trim());
+  const maxReturn = incremental ? 1e4 : tail;
+  const sliced = filtered.length > maxReturn ? filtered.slice(-maxReturn) : filtered;
+  return { records: sliced, latestTs };
+}
+function resolveIpcFileLogsDir(context, target) {
+  const holder = context;
+  const basePath = target.basePath ?? (holder.params?.get?.("tasksLogsBasePath") || "./data");
+  const namespace = target.namespace ?? (holder.params?.get?.("tasksLogsNamespace") || "tasks-logs");
+  const segments = target.tableName.split("/").filter(Boolean);
+  return path4.resolve(basePath, namespace, ...segments);
+}
+function getLogsStateForTarget(context, target) {
+  const holder = context;
+  const enabledRaw = holder.params?.get?.("tasksLogsEnabled");
+  const enabled = enabledRaw === void 0 ? true : !!enabledRaw;
+  if (!enabled) return null;
+  if (!holder.__tasksLogsTargetStates) holder.__tasksLogsTargetStates = /* @__PURE__ */ new Map();
+  const map = holder.__tasksLogsTargetStates;
+  const key = ipcLogTargetKey(target);
+  if (map.has(key)) return map.get(key);
+  const basePath = target.basePath ?? (holder.params?.get?.("tasksLogsBasePath") || "./data");
+  const namespace = target.namespace ?? (holder.params?.get?.("tasksLogsNamespace") || "tasks-logs");
+  const maxVersionsRaw = Number(holder.params?.get?.("tasksLogsMaxVersions"));
+  const pageSizeRaw = Number(holder.params?.get?.("tasksLogsPageSize"));
+  const db = new FileDatabase({
+    basePath,
+    namespace,
+    tableName: target.tableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: Number.isFinite(maxVersionsRaw) && maxVersionsRaw > 0 ? maxVersionsRaw : 20,
+    pageSize: Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 2e3,
+    logger: holder.logger
+  });
+  const state = {
+    db,
+    errorDb: null,
+    queue: Promise.resolve(),
+    initialized: false,
+    errorInitialized: false
+  };
+  map.set(key, state);
+  return state;
+}
 function isErrorPayload(payload) {
   if (!payload) return false;
   if (typeof payload === "object") {
@@ -1315,14 +1747,26 @@ function buildLogRecord(task, payload) {
     ts: (/* @__PURE__ */ new Date()).toISOString(),
     opid: task.opid ?? null,
     taskId: task.id,
-    taskName: task.task,
-    target: task.target,
+    taskName: task.name,
+    target: task.service_group,
     source: typeof params.source === "string" ? params.source : null,
     resource: typeof params.resource === "string" ? params.resource : null,
     payload
   };
 }
-function appendTaskIpcLog(context, task, payload) {
+function appendTaskIpcLog(context, task, payload, target) {
+  if (target) {
+    const state2 = getLogsStateForTarget(context, target);
+    if (!state2?.db) return;
+    const record2 = buildLogRecord(task, payload);
+    state2.queue = state2.queue.then(async () => {
+      await state2.db.write([record2], { forceNewVersion: !state2.initialized });
+      state2.initialized = true;
+    }).catch((error) => {
+      context.logger.warn?.("[tasks] failed to persist IPC log entry (targeted):", error);
+    });
+    return;
+  }
   const state = getLogsState(context);
   if (!state.db && !state.errorDb) return;
   const record = buildLogRecord(task, payload);
@@ -1339,98 +1783,315 @@ function appendTaskIpcLog(context, task, payload) {
     context.logger.warn?.("[tasks] failed to persist IPC log entry:", error);
   });
 }
-
-// src/tasks/time-matcher.ts
-var RANGES = ["0-59", "0-59", "0-23", "1-31", "1-12", "0-6"];
-function resolveAsterisks(field, range) {
-  return field.includes("*") ? field.replace("*", range) : field;
-}
-function resolveRanges(field) {
-  const regex = /(\d+)-(\d+)/;
-  let current = field;
-  while (true) {
-    const match = regex.exec(current);
-    if (!match) break;
-    const raw = match[0];
-    let first = Number(match[1]);
-    let last = Number(match[2]);
-    if (last < first) {
-      [first, last] = [last, first];
-    }
-    const values = [];
-    for (let i = first; i <= last; i += 1) {
-      values.push(i);
+async function flushTaskIpcLogs(context) {
+  const holder = context;
+  const promises = [];
+  if (holder.__tasksLogsState?.queue) promises.push(holder.__tasksLogsState.queue);
+  const map = holder.__tasksLogsTargetStates;
+  if (map) {
+    for (const s of map.values()) {
+      if (s.queue) promises.push(s.queue);
     }
-    current = current.replace(raw, values.join(","));
-  }
-  return current;
-}
-function resolveSteps(field) {
-  const match = /^(.+)\/(\d+)$/.exec(field);
-  if (!match) return field;
-  const base = match[1];
-  const step = Number(match[2]);
-  if (!Number.isFinite(step) || step <= 0) return field;
-  return base.split(",").map((v) => Number(v)).filter((v) => Number.isFinite(v) && v % step === 0).join(",");
-}
-function convertPattern(pattern) {
-  const parts = pattern.trim().split(/\s+/);
-  if (parts.length !== 6) {
-    throw new Error(`Invalid schedule "${pattern}". Expected 6 fields: sec min hour day month weekday`);
   }
-  return parts.map((field, idx) => resolveAsterisks(field, RANGES[idx])).map((field) => resolveRanges(field)).map((field) => resolveSteps(field));
-}
-function fieldMatches(field, value) {
-  const allowed = field.split(",").map((v) => Number(v));
-  return allowed.includes(value);
-}
-function timeMatcher(pattern, date = /* @__PURE__ */ new Date()) {
-  const parsed = convertPattern(pattern);
-  return fieldMatches(parsed[0], date.getSeconds()) && fieldMatches(parsed[1], date.getMinutes()) && fieldMatches(parsed[2], date.getHours()) && fieldMatches(parsed[3], date.getDate()) && fieldMatches(parsed[4], date.getMonth() + 1) && fieldMatches(parsed[5], date.getDay());
+  await Promise.all(promises);
 }
 
-// src/tasks/TaskMaster.ts
-var TaskMaster = class {
-  context;
-  task;
+// src/tasks/AbstractTask.js
+var AbstractTask = class _AbstractTask {
+  /**
+   * Whether `send-task` should wait for completion (and print a result
+   * report) when no explicit `--wait` / `--noWait` flag is given. Defaults
+   * to false; short-lived probe tasks (e.g. `ping`) override to true.
+   *
+   * @type {boolean}
+   */
+  static defaultWaitForResult = false;
+  /**
+   * @param {object} context Runner context (db, logger, params, emitter...).
+   * @param {object} task    Task row as claimed from the queue.
+   */
   constructor(context, task) {
     this.context = context;
     this.task = task;
   }
+  /**
+   * Return a short reason string when the task should be deferred (e.g. "locked
+   * by source"), or `false`/falsy when it is free to run. Default: always `false`.
+   *
+   * @returns {string | false | Promise<string | false>}
+   */
   cantRunReason() {
     return false;
   }
+  /**
+   * Called by the runner when a stop has been requested. Subclasses running
+   * long loops should flip a flag here and check it between iterations.
+   *
+   * @param {number} [_allowanceMs] Grace period the runner promises before hard exit.
+   */
   requestStop(_allowanceMs) {
   }
-};
-
-// src/tasks/coreTasks/TaskPing.ts
-var TaskPing = class extends TaskMaster {
-  async run() {
-    this.context.logger.info?.(`[TaskPing] pong (${this.task.id})`);
-    return { success: true, results: "pong" };
+  /**
+   * Perform the task. Must be implemented by subclasses.
+   *
+   * @param {(progress: unknown) => Promise<void>} _reportProgress
+   *        Updates the DB `progress` column. Accepts any serializable value;
+   *        strings are stored verbatim, objects are JSON-stringified.
+   * @returns {Promise<{ success: boolean, results: unknown }>}
+   */
+  async run(_reportProgress) {
+    throw new Error("AbstractTask.run must be implemented by subclass");
   }
-};
-
-// src/tasks/coreTasks/TaskSampleProcess.ts
-var TaskSampleProcess = class extends TaskMaster {
-  stopRequested = false;
-  stopAllowanceMs = 0;
-  stopDecisionLogged = false;
-  requestStop(allowanceMs) {
-    this.stopRequested = true;
-    this.stopAllowanceMs = Number.isFinite(allowanceMs) && allowanceMs > 0 ? allowanceMs : 0;
-    this.context.logger.warn?.(
-      `[TaskSampleProcess] stop signal received (${this.task.id}), allowanceMs=${this.stopAllowanceMs}`
-    );
+  /**
+   * Resolve a complete row payload for this task — envelope fields (queue,
+   * priority, targeting, schedule…) plus the inner `params` blob produced by
+   * {@link AbstractTask.resolveCustomParams}. Output shape matches
+   * {@link enqueueTask}'s `options` argument, so the typical call is:
+   *
+   *   const payload = await TaskClass.resolveParams(context, { name });
+   *   await enqueueTask(context, payload);
+   *
+   * Validation failures throw {@link ParamError} so the script aborts before
+   * a malformed row hits the DB.
+   *
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides] Partial overrides; takes precedence over CLI/env.
+   *   Recognised keys: `name`, `queueName`, `priority`, `serviceGroup`,
+   *   `serviceName`, `instanceNumber`, `serverName`, `opid`, `schedule`,
+   *   `nextRunAt`, plus `params` (object — overlay onto inner blob).
+   * @returns {Promise<object>}
+   */
+  static async resolveParams(context, overrides = {}) {
+    const main = _AbstractTask._resolveMainFields(context, overrides);
+    const params = await this.resolveCustomParams(context, overrides);
+    return { ...main, params };
   }
-  async run(reportProgress) {
-    const totalRaw = this.task?.params?.total ?? 10;
-    const delayRaw = this.task?.params?.delay ?? 1e3;
-    const nameRaw = this.task?.params?.name;
-    const total = Number(totalRaw);
-    const delay = Number(delayRaw);
-    const name = typeof nameRaw === "string" && nameRaw.trim() ? nameRaw.trim() : "sampleProcess";
+  /**
+   * Resolve the inner JSON blob stored in the `params` column. Default
+   * implementation passes through `--paramsJson` (parsed as a JSON object)
+   * overlaid with `overrides.params` when supplied; returns `null` when
+   * neither is provided.
+   *
+   * Subclasses with typed fields should override and call
+   * {@link AbstractTask._mergeTypedParams} for layered CLI/env/JSON/override
+   * resolution, then validate and throw {@link ParamError} on bad input.
+   *
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<object|null>}
+   */
+  static async resolveCustomParams(context, overrides = {}) {
+    return _AbstractTask._defaultParamsBlob(context, overrides);
+  }
+  /**
+   * Read main task envelope fields from `context.params` (CLI/env), with
+   * any matching key on `overrides` taking precedence. Internal; called by
+   * {@link AbstractTask.resolveParams}.
+   *
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {object}
+   */
+  static _resolveMainFields(context, overrides = {}) {
+    const defs = {
+      queueName: "string default tasks",
+      priority: "number default 50",
+      serviceGroup: "string",
+      serviceName: "string",
+      instanceNumber: "number",
+      serverName: "string",
+      opid: "string",
+      schedule: "string"
+    };
+    const cli = context.params.getAllForModule("task-envelope", defs);
+    const name = emptyToUndef(overrides.name) ?? emptyToUndef(context.params.get("name", "string"));
+    if (!name) {
+      throw new ParamError("Task --name is required (e.g. ping, stop, dummyHarvest)");
+    }
+    let instanceNumber;
+    const rawInstance = overrides.instanceNumber ?? cli.instanceNumber;
+    if (rawInstance !== void 0 && rawInstance !== null && String(rawInstance).trim() !== "") {
+      const n = Number(rawInstance);
+      if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1) {
+        throw new ParamError("--instanceNumber must be a positive integer when set");
+      }
+      instanceNumber = n;
+    } else {
+      instanceNumber = null;
+    }
+    const priorityRaw = overrides.priority ?? cli.priority ?? 50;
+    const priority = Number(priorityRaw);
+    if (!Number.isFinite(priority)) {
+      throw new ParamError(`--priority must be a number (got ${JSON.stringify(priorityRaw)})`);
+    }
+    return {
+      name,
+      queueName: overrides.queueName ?? emptyToUndef(cli.queueName) ?? "tasks",
+      priority,
+      serviceGroup: emptyToUndef(overrides.serviceGroup) ?? emptyToUndef(cli.serviceGroup) ?? null,
+      serviceName: emptyToUndef(overrides.serviceName) ?? emptyToUndef(cli.serviceName) ?? null,
+      instanceNumber,
+      serverName: emptyToUndef(overrides.serverName) ?? emptyToUndef(cli.serverName) ?? null,
+      opid: emptyToUndef(overrides.opid) ?? emptyToUndef(cli.opid) ?? null,
+      schedule: emptyToUndef(overrides.schedule) ?? emptyToUndef(cli.schedule) ?? null,
+      nextRunAt: overrides.nextRunAt ?? null
+    };
+  }
+  /**
+   * Default inner-params resolver: parses `--paramsJson` (must be a JSON
+   * object), then overlays `overrides.params` on top. Returns `null` when
+   * neither is provided.
+   *
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {object|null}
+   */
+  static _defaultParamsBlob(context, overrides = {}) {
+    const cli = context.params.getAllForModule("task-params", { paramsJson: "string" });
+    const fromJson = parseParamsJson(cli.paramsJson);
+    const fromOverride = pickParamsObject(overrides);
+    if (!fromJson && !fromOverride) return null;
+    return { ...fromJson ?? {}, ...fromOverride ?? {} };
+  }
+  /**
+   * Helper for subclass `resolveCustomParams` overrides. Reads typed CLI
+   * params (per `defs`) plus `--paramsJson` under a module namespace, then
+   * merges them with explicit `overrides.params` in increasing priority:
+   *
+   *   typed CLI flags → --paramsJson → overrides.params
+   *
+   * Undefined values are dropped so defaults declared in `defs` aren't
+   * overwritten by missing-flag noise. Returns the merged object; the
+   * caller is responsible for validation and throwing `ParamError`.
+   *
+   * @param {object} context
+   * @param {string} moduleName Namespace for `--showUsedParams` grouping.
+   * @param {Record<string, string>} defs Param defs in `getAllForModule` syntax.
+   * @param {Record<string, unknown>} [overrides] As passed to `resolveCustomParams`.
+   * @returns {Record<string, unknown>}
+   */
+  static _mergeTypedParams(context, moduleName, defs, overrides = {}) {
+    const fullDefs = { ...defs, paramsJson: "string" };
+    const cliRaw = context.params.getAllForModule(moduleName, fullDefs);
+    const fromJson = parseParamsJson(cliRaw.paramsJson) ?? {};
+    const fromCli = {};
+    for (const [k, v] of Object.entries(cliRaw)) {
+      if (k === "paramsJson") continue;
+      if (v !== void 0 && v !== null) fromCli[k] = v;
+    }
+    const fromOverride = pickParamsObject(overrides) ?? {};
+    return { ...fromCli, ...fromJson, ...fromOverride };
+  }
+};
+function emptyToUndef(s) {
+  if (s === void 0 || s === null) return void 0;
+  if (typeof s !== "string") return s;
+  const t = s.trim();
+  return t.length ? t : void 0;
+}
+function parseParamsJson(raw) {
+  if (raw == null) return null;
+  const t = String(raw).trim();
+  if (!t) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(t);
+  } catch (e) {
+    throw new ParamError(`--paramsJson: not valid JSON: ${e?.message ?? String(e)}`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new ParamError("--paramsJson must be a JSON object");
+  }
+  return parsed;
+}
+function pickParamsObject(overrides) {
+  const p = overrides?.params;
+  if (p && typeof p === "object" && !Array.isArray(p)) return p;
+  return void 0;
+}
+
+// src/tasks/coreTasks/TaskPing.js
+var TaskPing = class extends AbstractTask {
+  /** Default-wait so `send-task --name=ping` prints a result without `--wait`. */
+  static defaultWaitForResult = true;
+  /** Ping takes no params. */
+  static async resolveCustomParams() {
+    return null;
+  }
+  /**
+   * @returns {Promise<{ success: true, results: "pong" }>}
+   */
+  async run() {
+    this.context.logger.info?.(`[TaskPing] pong (${this.task.id})`);
+    return { success: true, results: "pong" };
+  }
+};
+
+// src/tasks/coreTasks/TaskSampleProcess.js
+var TaskSampleProcess = class extends AbstractTask {
+  /**
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<{ total: number, delay: number, name?: string }>}
+   */
+  static async resolveCustomParams(context, overrides = {}) {
+    const merged = AbstractTask._mergeTypedParams(context, "task-sample-process", {
+      total: "number default 10",
+      delay: "number default 1000",
+      name: "string"
+    }, overrides);
+    const total = Number(merged.total);
+    const delay = Number(merged.delay);
+    if (!Number.isInteger(total) || total <= 0) {
+      throw new ParamError(`sampleProcess: param "total" must be a positive integer (got ${JSON.stringify(merged.total)})`);
+    }
+    if (!Number.isInteger(delay) || delay < 0) {
+      throw new ParamError(`sampleProcess: param "delay" must be an integer >= 0 (got ${JSON.stringify(merged.delay)})`);
+    }
+    const out = { total, delay };
+    if (typeof merged.name === "string" && merged.name.trim()) {
+      out.name = merged.name.trim();
+    }
+    return out;
+  }
+  /**
+   * @param {object} context
+   * @param {object} task
+   */
+  constructor(context, task) {
+    super(context, task);
+    this.stopRequested = false;
+    this.stopAllowanceMs = 0;
+    this.stopDecisionLogged = false;
+  }
+  /**
+   * Runner-facing stop signal. Records the allowance window so the main loop
+   * can decide per-iteration whether to finish or abort early.
+   *
+   * @param {number} allowanceMs
+   */
+  requestStop(allowanceMs) {
+    this.stopRequested = true;
+    this.stopAllowanceMs = Number.isFinite(allowanceMs) && allowanceMs > 0 ? allowanceMs : 0;
+    this.context.logger.warn?.(
+      `[TaskSampleProcess] stop signal received (${this.task.id}), allowanceMs=${this.stopAllowanceMs}`
+    );
+  }
+  /**
+   * Iterate `total` times, sleeping `delay` ms between ticks and reporting
+   * progress every iteration. Validates params up front; invalid values short-
+   * circuit to a structured failure without starting the loop.
+   *
+   * @param {(progress: object) => Promise<void>} reportProgress
+   * @returns {Promise<{ success: boolean, results: unknown }>}
+   */
+  async run(reportProgress) {
+    const totalRaw = this.task?.params?.total ?? 10;
+    const delayRaw = this.task?.params?.delay ?? 1e3;
+    const nameRaw = this.task?.params?.name;
+    const total = Number(totalRaw);
+    const delay = Number(delayRaw);
+    const name = typeof nameRaw === "string" && nameRaw.trim() ? nameRaw.trim() : "sampleProcess";
     const errors = [];
     if (!Number.isInteger(total) || total <= 0) {
       errors.push('param "total" must be a positive integer');
@@ -1505,7 +2166,7 @@ var TaskSampleProcess = class extends TaskMaster {
   }
 };
 
-// src/tasks/coreTasks/TaskShellCommand.ts
+// src/tasks/coreTasks/TaskShellCommand.js
 import { spawn } from "child_process";
 function runShellCommand(command, cwd) {
   return new Promise((resolve, reject) => {
@@ -1535,7 +2196,27 @@ function runShellCommand(command, cwd) {
     });
   });
 }
-var TaskShellCommand = class extends TaskMaster {
+var TaskShellCommand = class extends AbstractTask {
+  /**
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<{ command: string, cwd?: string }>}
+   */
+  static async resolveCustomParams(context, overrides = {}) {
+    const merged = AbstractTask._mergeTypedParams(context, "task-shell", {
+      command: "string",
+      cwd: "string"
+    }, overrides);
+    const command = typeof merged.command === "string" ? merged.command.trim() : "";
+    if (!command) {
+      throw new ParamError('shellCommand: param "command" must be a non-empty string');
+    }
+    const cwd = typeof merged.cwd === "string" && merged.cwd.trim() ? merged.cwd.trim() : null;
+    return cwd ? { command, cwd } : { command };
+  }
+  /**
+   * @returns {Promise<{ success: boolean, results: unknown }>}
+   */
   async run() {
     const params = this.task?.params;
     const commandRaw = typeof params === "string" ? params : params?.command;
@@ -1584,8 +2265,8 @@ var TaskShellCommand = class extends TaskMaster {
   }
 };
 
-// src/tasks/coreTasks/TaskSystemInfo.ts
-import os from "os";
+// src/tasks/coreTasks/TaskSystemInfo.js
+import os2 from "os";
 import fs4 from "fs/promises";
 function toGb(valueBytes) {
   return `${(valueBytes / 1024 ** 3).toFixed(2)} GB`;
@@ -1604,13 +2285,22 @@ async function getDiskStats() {
     free: toGb(free)
   };
 }
-var TaskSystemInfo = class extends TaskMaster {
+var TaskSystemInfo = class extends AbstractTask {
+  /** Same UX expectation as `ping` — short probe, print the result. */
+  static defaultWaitForResult = true;
+  /** systemInfo takes no params. */
+  static async resolveCustomParams() {
+    return null;
+  }
+  /**
+   * @returns {Promise<{ success: boolean, results: unknown }>}
+   */
   async run() {
     try {
-      const totalMemory = os.totalmem();
-      const freeMemory = os.freemem();
+      const totalMemory = os2.totalmem();
+      const freeMemory = os2.freemem();
       const usedMemory = totalMemory - freeMemory;
-      const cpus = os.cpus();
+      const cpus = os2.cpus();
       const cpuUtilization = cpus.map((cpu) => {
         const total = Object.values(cpu.times).reduce((acc, time) => acc + time, 0);
         const usage = (total - cpu.times.idle) / total * 100;
@@ -1636,10 +2326,10 @@ var TaskSystemInfo = class extends TaskMaster {
           utilization: cpuUtilization
         },
         runtime: {
-          platform: os.platform(),
-          arch: os.arch(),
-          uptimeSec: os.uptime(),
-          hostname: os.hostname()
+          platform: os2.platform(),
+          arch: os2.arch(),
+          uptimeSec: os2.uptime(),
+          hostname: os2.hostname()
         }
       };
       this.context.logger.info?.(`[TaskSystemInfo] collected system metrics (${this.task.id})`);
@@ -1656,8 +2346,31 @@ var TaskSystemInfo = class extends TaskMaster {
   }
 };
 
-// src/tasks/coreTasks/TaskSumAB.ts
-var TaskSumAB = class extends TaskMaster {
+// src/tasks/coreTasks/TaskSumAB.js
+var TaskSumAB = class extends AbstractTask {
+  /** Short, deterministic — wait by default so callers see the sum. */
+  static defaultWaitForResult = true;
+  /**
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<{ a: number, b: number }>}
+   */
+  static async resolveCustomParams(context, overrides = {}) {
+    const merged = AbstractTask._mergeTypedParams(context, "task-sumab", {
+      a: "number",
+      b: "number"
+    }, overrides);
+    if (typeof merged.a !== "number" || Number.isNaN(merged.a)) {
+      throw new ParamError(`taskSumAB: param "a" must be a valid number (got ${JSON.stringify(merged.a)})`);
+    }
+    if (typeof merged.b !== "number" || Number.isNaN(merged.b)) {
+      throw new ParamError(`taskSumAB: param "b" must be a valid number (got ${JSON.stringify(merged.b)})`);
+    }
+    return { a: merged.a, b: merged.b };
+  }
+  /**
+   * @returns {Promise<{ success: boolean, results: unknown }>}
+   */
   async run() {
     const a = this.task?.params?.a;
     const b = this.task?.params?.b;
@@ -1688,8 +2401,46 @@ var TaskSumAB = class extends TaskMaster {
   }
 };
 
-// src/tasks/coreTasks/TaskStopRunner.ts
-var TaskStopRunner = class extends TaskMaster {
+// src/tasks/coreTasks/TaskStopRunner.js
+var TaskStopRunner = class extends AbstractTask {
+  /**
+   * Stop tasks must target a concrete instance — without `serviceName` the
+   * row would race against any worker on the queue. Layered on top of the
+   * envelope built by {@link AbstractTask.resolveParams}.
+   *
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<object>}
+   */
+  static async resolveParams(context, overrides = {}) {
+    const main = await super.resolveParams(context, overrides);
+    if (!main.serviceName) {
+      throw new ParamError(
+        "stop/stopRunner requires --serviceName (registry instance name; optional --serviceGroup, --instanceNumber, --serverName to narrow targeting)"
+      );
+    }
+    return main;
+  }
+  /**
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<{ allowanceMs: number }>}
+   */
+  static async resolveCustomParams(context, overrides = {}) {
+    const merged = AbstractTask._mergeTypedParams(context, "task-stop", {
+      allowanceMs: "number default 5000"
+    }, overrides);
+    const allowanceMs = Number(merged.allowanceMs);
+    if (!Number.isFinite(allowanceMs) || allowanceMs < 0) {
+      throw new ParamError(
+        `stopRunner: allowanceMs must be a non-negative number (got ${JSON.stringify(merged.allowanceMs)})`
+      );
+    }
+    return { allowanceMs };
+  }
+  /**
+   * @returns {Promise<{ success: true, results: { stopRunner: true, allowanceMs: number, message: string } }>}
+   */
   async run() {
     const allowanceMs = Number(this.task?.params?.allowanceMs ?? 5e3);
     this.context.logger.warn?.(`[TaskStopRunner] stop requested (allowanceMs=${allowanceMs})`);
@@ -1704,175 +2455,399 @@ var TaskStopRunner = class extends TaskMaster {
   }
 };
 
-// src/tasks/TasksRegistry.ts
+// src/tasks/coreTasks/TaskGetLogs.js
+var TaskGetLogs = class extends AbstractTask {
+  /**
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<{ source: string, resource: string, tail: number, afterTs?: string }>}
+   */
+  static async resolveCustomParams(context, overrides = {}) {
+    const merged = AbstractTask._mergeTypedParams(context, "task-get-logs", {
+      source: "string",
+      resource: "string",
+      tail: "number default 100",
+      afterTs: "string"
+    }, overrides);
+    const source = typeof merged.source === "string" ? merged.source.trim() : "";
+    const resource = typeof merged.resource === "string" ? merged.resource.trim() : "";
+    if (!source) throw new ParamError('getLogs: param "source" is required');
+    if (!resource) throw new ParamError('getLogs: param "resource" is required');
+    let tail = Number(merged.tail);
+    if (!Number.isFinite(tail) || tail < 1) tail = 100;
+    tail = Math.min(1e4, Math.max(1, Math.floor(tail)));
+    const out = { source, resource, tail };
+    if (typeof merged.afterTs === "string" && merged.afterTs.trim()) {
+      out.afterTs = merged.afterTs.trim();
+    }
+    return out;
+  }
+  /**
+   * @param {unknown} _reportProgress Unused (single-shot read, no progress events).
+   * @returns {Promise<{ success: boolean, results: unknown }>}
+   */
+  async run(_reportProgress) {
+    const p = this.task.params ?? {};
+    const source = String(p.source ?? "").trim();
+    const resource = String(p.resource ?? "").trim();
+    const tail = Math.max(1, Math.min(1e4, Number(p.tail) > 0 ? Number(p.tail) : 100));
+    const afterTs = p.afterTs != null && String(p.afterTs).trim() ? String(p.afterTs).trim() : null;
+    if (!source || !resource) {
+      return {
+        success: false,
+        results: { error: 'getLogs requires params "source" and "resource"' }
+      };
+    }
+    try {
+      const { records, latestTs } = await readTaskIpcLogsSnapshot(this.context, {
+        source,
+        resource,
+        tail,
+        afterTs
+      });
+      return {
+        success: true,
+        results: { records, latestTs, source, resource }
+      };
+    } catch (e) {
+      return {
+        success: false,
+        results: { error: e?.message ?? String(e) }
+      };
+    }
+  }
+};
+
+// src/tasks/TasksRegistry.js
 var TasksRegistry = class _TasksRegistry {
-  map = {};
+  /**
+   * @param {Record<string, Function>} [initial] Optional seed entries to copy in.
+   */
   constructor(initial) {
+    this.map = {};
     if (initial) {
       this.addMany(initial);
     }
   }
+  /**
+   * Build a registry pre-populated with every core task plus legacy aliases.
+   * Prefer this over `new TasksRegistry()` for anything that wants `ping`/`stop`/etc.
+   *
+   * @returns {TasksRegistry}
+   */
   static withCoreTasks() {
-    return new _TasksRegistry().add("ping", TaskPing).add("sampleProcess", TaskSampleProcess).add("shellCommand", TaskShellCommand).add("systemInfo", TaskSystemInfo).add("taskSumAB", TaskSumAB).add("stopRunner", TaskStopRunner).add("stop", TaskStopRunner);
+    return new _TasksRegistry().add("ping", TaskPing).add("sampleProcess", TaskSampleProcess).add("shellCommand", TaskShellCommand).add("systemInfo", TaskSystemInfo).add("info", TaskSystemInfo).add("taskSumAB", TaskSumAB).add("stopRunner", TaskStopRunner).add("stop", TaskStopRunner).add("getLogs", TaskGetLogs);
   }
+  /**
+   * Register a single task class under a name. Overwrites any previous entry.
+   *
+   * @param {string} taskName
+   * @param {Function} taskClass Subclass of `AbstractTask`.
+   * @returns {this}
+   */
   add(taskName, taskClass) {
     this.map[taskName] = taskClass;
     return this;
   }
+  /**
+   * Bulk-register a name → class map. Later calls override earlier ones.
+   *
+   * @param {Record<string, Function>} entries
+   * @returns {this}
+   */
   addMany(entries) {
     for (const [name, klass] of Object.entries(entries)) {
       this.add(name, klass);
     }
     return this;
   }
+  /**
+   * Look up a task class by name. Returns `undefined` when the name is unknown;
+   * the runner treats that as "some other worker may handle this" and skips.
+   *
+   * @param {string} taskName
+   * @returns {Function | undefined}
+   */
   get(taskName) {
     return this.map[taskName];
   }
+  /**
+   * Strict variant of {@link get}: throws {@link ParamError} (with the list
+   * of supported names) when `taskName` is unknown. Use from enqueuer code
+   * paths where an unknown name is a hard CLI/programmer error.
+   *
+   * @param {string} taskName
+   * @returns {Function}
+   */
+  requireClass(taskName) {
+    const TaskClass = taskName ? this.map[taskName] : void 0;
+    if (!TaskClass) {
+      const supported = this.listSupportedTasks().join(", ") || "(none)";
+      throw new ParamError(
+        `Unknown task "${taskName ?? ""}". Supported on this registry: ${supported}`
+      );
+    }
+    return TaskClass;
+  }
+  /**
+   * Dispatcher used by `send-task` / programmatic enqueuers: pick `name`
+   * from `overrides` or `context.params`, look up the class, and delegate
+   * to its static {@link AbstractTask.resolveParams} with `name` seeded into
+   * the overrides. The returned object is shaped for {@link enqueueTask}.
+   *
+   * Validation failures (unknown task, missing required custom params, etc.)
+   * surface as {@link ParamError} so the caller aborts cleanly before any
+   * row is inserted.
+   *
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<object>}
+   */
+  async resolveTaskParams(context, overrides = {}) {
+    const overrideName = typeof overrides.name === "string" ? overrides.name.trim() : overrides.name;
+    const fromCli = context.params.get("name", "string");
+    const cliName = typeof fromCli === "string" ? fromCli.trim() : fromCli;
+    const name = overrideName || cliName;
+    if (!name) {
+      throw new ParamError("Task --name is required (e.g. ping, stop, dummyHarvest)");
+    }
+    const TaskClass = this.requireClass(name);
+    return TaskClass.resolveParams(context, { ...overrides, name });
+  }
+  /**
+   * Names of every registered task, sorted alphabetically (useful for CLI output
+   * and allowlist sanity checks).
+   *
+   * @returns {string[]}
+   */
   listSupportedTasks() {
     return Object.keys(this.map).sort();
   }
+  /**
+   * Shallow copy of the internal map, for handing to `addMany` on another registry
+   * or for serialization.
+   *
+   * @returns {Record<string, Function>}
+   */
   toObject() {
     return { ...this.map };
   }
 };
 
-// src/tasks/taskScriptRunner.ts
+// src/tasks/serviceTaskAllowlist.js
+var SERVICE_TASK_NAMES = [
+  "ping",
+  "stop",
+  "stopRunner",
+  "shellCommand",
+  "systemInfo",
+  "info",
+  "getLogs"
+];
+function normalizeAllowedTasks(value) {
+  if (!value) return void 0;
+  if (Array.isArray(value)) {
+    const out2 = value.map((v) => String(v).trim()).filter(Boolean);
+    return out2.length ? out2 : void 0;
+  }
+  const out = String(value).split(",").map((v) => v.trim()).filter(Boolean);
+  return out.length ? out : void 0;
+}
+function mergeAllowedTasksWithServiceTasks(names) {
+  const set = /* @__PURE__ */ new Set([...SERVICE_TASK_NAMES, ...names ?? []]);
+  return Array.from(set).sort();
+}
+
+// src/tasks/taskScriptRunner.js
 import { spawn as spawn2 } from "child_process";
+var MAX_PROGRESS_TEXT_LEN = 4e3;
 function toCliArgs(args = []) {
   return args.filter((a) => typeof a === "string" && a.length > 0);
 }
 function formatChildLogPrefix(task) {
-  return `${task.task}:${task.id.slice(0, 8)}${task.opid ? `:${task.opid}` : ""}`;
+  return `${task.name}:${task.id.slice(0, 8)}${task.opid ? `:${task.opid}` : ""}`;
 }
-async function runNodeTaskScript(context, options) {
-  const cliArgs = toCliArgs(["--route=ipc", "--mode=json", ...options.args || []]);
+function isProgressPayload(payload) {
+  if (!payload || typeof payload !== "object") return false;
+  if (payload.level !== "progress") return false;
+  const count = Number(payload.count);
+  const total = Number(payload.total);
+  return Number.isFinite(count) && Number.isFinite(total) && total > 0;
+}
+function formatProgressText(payload, fallbackPrefix) {
+  const pfx = payload.prefix ? `${payload.prefix} ` : fallbackPrefix ? `${fallbackPrefix} ` : "";
+  const label = typeof payload.message === "string" && payload.message ? `${payload.message} ` : "";
+  return `${pfx}${label}${payload.count}/${payload.total}`;
+}
+function forwardChildLogToParent(context, prefix, message) {
+  if (!message || typeof message !== "object") return;
+  const text = typeof message.message === "string" ? message.message : null;
+  if (!text) return;
+  const level = typeof message.level === "string" ? message.level.toLowerCase() : "";
+  const line = `[child:${prefix}] ${text}`;
+  const logger = context.logger;
+  switch (level) {
+    case "error":
+    case "fatal":
+      logger.error?.(line);
+      return;
+    case "warn":
+    case "warning":
+      logger.warn?.(line);
+      return;
+    case "debug":
+      logger.debug?.(line);
+      return;
+    case "info":
+    default:
+      logger.info?.(line);
+  }
+}
+function buildNodeArgs(scriptPath, cliArgs) {
   const inheritedExecArgs = Array.isArray(process.execArgv) ? [...process.execArgv] : [];
   const hasTsRuntimeInParent = inheritedExecArgs.some((arg) => /tsx|ts-node/i.test(arg));
-  const nodeArgs = hasTsRuntimeInParent ? [...inheritedExecArgs, options.scriptPath, ...cliArgs] : ["--import", "tsx", options.scriptPath, ...cliArgs];
-  const child = spawn2(
-    process.execPath,
-    nodeArgs,
-    {
-      cwd: options.cwd || process.cwd(),
-      stdio: ["ignore", "pipe", "pipe", "ipc"],
-      env: {
-        ...process.env,
-        TASK_ID: options.task.id,
-        TASK_NAME: options.task.task,
-        TASK_OPID: options.task.opid || ""
-      }
-    }
+  return hasTsRuntimeInParent ? [...inheritedExecArgs, scriptPath, ...cliArgs] : ["--import", "tsx", scriptPath, ...cliArgs];
+}
+function resolveTasksTableName(context) {
+  return context.tasksQueueName || context.params?.get?.("table") || "tasks";
+}
+function announceIpcFileLogsTarget(context, options) {
+  if (!options.ipcFileLogs) return;
+  const logsDir = resolveIpcFileLogsDir(context, options.ipcFileLogs);
+  const enabledRaw = context.params?.get?.("tasksLogsEnabled");
+  const logsEnabled = enabledRaw === void 0 ? true : !!enabledRaw;
+  context.logger.info?.(
+    `[tasks] IPC file logs: ${logsDir}` + (logsEnabled ? "" : " (tasksLogsEnabled=false; not persisted)")
   );
-  let stdout = "";
-  let stderr = "";
-  let workerResult = null;
-  let hadErrorMessage = false;
-  const prefix = formatChildLogPrefix(options.task);
-  const db = context.db;
-  const tasksTable = context.params?.get?.("table") || "tasks";
-  let progressWriteChain = Promise.resolve();
-  let progressCallbackChain = Promise.resolve();
-  const updateProgress = (text) => {
-    if (!db || !text || !text.trim()) return;
-    progressWriteChain = progressWriteChain.then(async () => {
-      await db(tasksTable).where({ id: options.task.id }).update({ progress: text.slice(0, 4e3) });
-    }).catch((error) => {
-      context.logger.warn?.(
-        `[tasks] failed to update progress for task=${options.task.id}: ${error?.message ?? String(error)}`
-      );
-    });
-    if (options.onProgress) {
-      progressCallbackChain = progressCallbackChain.then(async () => {
-        await options.onProgress?.(text.slice(0, 4e3));
-      }).catch((error) => {
-        context.logger.warn?.(
-          `[tasks] reportProgress callback failed for task=${options.task.id}: ${error?.message ?? String(error)}`
-        );
+}
+function createSerializedQueue() {
+  let chain = Promise.resolve();
+  return {
+    push(fn) {
+      chain = chain.then(fn, () => {
+      }).catch(() => {
+      });
+      return chain;
+    },
+    drain() {
+      return chain.catch(() => {
       });
     }
   };
-  const payloadToProgressText = (payload) => {
-    if (!payload) return "";
-    if (typeof payload === "string") return payload;
-    if (typeof payload.message === "string" && payload.level === "progress" && payload.count !== void 0 && payload.total !== void 0) {
-      const pfx = payload.prefix ? `${payload.prefix} ` : "";
-      return `${pfx}${payload.message} ${payload.count}/${payload.total}`;
-    }
-    if (typeof payload.message === "string") return payload.message;
-    if (payload.level === "progress" && payload.count !== void 0 && payload.total !== void 0) {
-      const pfx = payload.prefix ? `${payload.prefix} ` : "";
-      return `${pfx}${payload.count}/${payload.total}`;
-    }
-    return "";
+}
+async function runNodeTaskScript(context, options) {
+  const cliArgs = toCliArgs(["--route=ipc", "--mode=json", ...options.args || []]);
+  const nodeArgs = buildNodeArgs(options.scriptPath, cliArgs);
+  const child = spawn2(process.execPath, nodeArgs, {
+    cwd: options.cwd || process.cwd(),
+    stdio: ["ignore", "pipe", "pipe", "ipc"],
+    env: {
+      ...process.env,
+      TASK_ID: options.task.id,
+      TASK_NAME: options.task.name,
+      TASK_OPID: options.task.opid || ""
+    }
+  });
+  announceIpcFileLogsTarget(context, options);
+  const prefix = formatChildLogPrefix(options.task);
+  const tasksTable = resolveTasksTableName(context);
+  const progressQueue = createSerializedQueue();
+  const state = {
+    stdout: "",
+    stderr: "",
+    workerResult: null,
+    hadErrorMessage: false
   };
-  child.stdout.on("data", (chunk) => {
+  const writeProgress = (text) => {
+    const trimmed = typeof text === "string" ? text.slice(0, MAX_PROGRESS_TEXT_LEN) : "";
+    if (!trimmed) return;
+    progressQueue.push(async () => {
+      const db = context.db;
+      if (db) {
+        try {
+          await db(tasksTable).where({ id: options.task.id }).update({ progress: trimmed });
+        } catch (error) {
+          context.logger.warn?.(
+            `[tasks] failed to update progress for task=${options.task.id}: ${error?.message ?? String(error)}`
+          );
+        }
+      }
+      if (options.onProgress) {
+        try {
+          await options.onProgress(trimmed);
+        } catch (error) {
+          context.logger.warn?.(
+            `[tasks] reportProgress callback failed for task=${options.task.id}: ${error?.message ?? String(error)}`
+          );
+        }
+      }
+    });
+  };
+  child.stdout?.on("data", (chunk) => {
     const text = String(chunk);
-    stdout += text;
+    state.stdout += text;
     if (text.trim()) {
       context.logger.info?.(`[child:${prefix}] ${text.trimEnd()}`);
-      updateProgress(text.trim().replace(/\s+/g, " ").slice(0, 400));
     }
   });
-  child.stderr.on("data", (chunk) => {
+  child.stderr?.on("data", (chunk) => {
     const text = String(chunk);
-    stderr += text;
+    state.stderr += text;
     if (text.trim()) {
       context.logger.warn?.(`[child:${prefix}] ${text.trimEnd()}`);
     }
   });
   child.on("message", (message) => {
     if (message && typeof message === "object" && "__taskWorkerResult" in message) {
-      workerResult = message.__taskWorkerResult;
+      state.workerResult = message.__taskWorkerResult;
       return;
     }
     if (message && typeof message === "object") {
       const level = typeof message.level === "string" ? message.level.toLowerCase() : "";
       if (level === "error" || level === "fatal") {
-        hadErrorMessage = true;
+        state.hadErrorMessage = true;
       }
     }
-    appendTaskIpcLog(context, options.task, message);
-    const progressText = payloadToProgressText(message);
-    if (progressText) {
-      updateProgress(progressText);
-      if (typeof message === "object" && message?.level === "progress" && message.count !== void 0 && message.total !== void 0) {
-        const countNum = Number(String(message.count).trim());
-        const totalNum = Number(message.total);
-        if (Number.isFinite(countNum) && Number.isFinite(totalNum) && totalNum > 0) {
-          context.logger.progress(message.message || "progress", {
-            prefix: message.prefix || prefix,
-            count: countNum,
-            total: totalNum
-          });
-        } else {
-          context.logger.info?.(`[child:${prefix}] ${progressText}`);
-        }
-      } else {
-        context.logger.info?.(`[child:${prefix}] ${progressText}`);
-      }
+    appendTaskIpcLog(context, options.task, message, options.ipcFileLogs);
+    try {
+      options.onChildIpcMessage?.(message);
+    } catch (e) {
+      context.logger.warn?.(`[tasks] onChildIpcMessage failed: ${e?.message ?? String(e)}`);
     }
+    if (isProgressPayload(message)) {
+      context.logger.progress(message.message || "progress", {
+        prefix: message.prefix || prefix,
+        count: Number(message.count),
+        total: Number(message.total)
+      });
+      writeProgress(formatProgressText(message, prefix));
+      return;
+    }
+    forwardChildLogToParent(context, prefix, message);
   });
   return await new Promise((resolve, reject) => {
     child.on("error", (error) => reject(error));
     child.on("close", (exitCode, signal) => {
-      Promise.allSettled([progressWriteChain, progressCallbackChain]).finally(() => {
+      void (async () => {
+        await flushTaskIpcLogs(context);
+        await progressQueue.drain();
         resolve({
           exitCode,
           signal,
-          stdout: stdout.trim(),
-          stderr: stderr.trim(),
-          workerResult,
-          hadErrorMessage
+          stdout: state.stdout.trim(),
+          stderr: state.stderr.trim(),
+          workerResult: state.workerResult,
+          hadErrorMessage: state.hadErrorMessage
         });
-      });
+      })();
     });
   });
 }
 
-// src/tasks/index.ts
+// src/tasks/index.js
 var LOCKED_BY_ERROR_MESSAGE = "locked by error";
 var defaultTasksRegistry = TasksRegistry.withCoreTasks();
-function getDb2(context) {
+function getDb3(context) {
   const db = context.db;
   if (!db) {
     throw new Error("Tasks component requires context.db. Initialize DB first and attach to context.");
@@ -1884,22 +2859,13 @@ function normalizeRegistry(registry) {
   if (registry instanceof TasksRegistry) return registry;
   return new TasksRegistry().addMany(registry);
 }
-function normalizeAllowedTasks(value) {
-  if (!value) return void 0;
-  if (Array.isArray(value)) {
-    const out2 = value.map((v) => String(v).trim()).filter(Boolean);
-    return out2.length ? out2 : void 0;
-  }
-  const out = String(value).split(",").map((v) => v.trim()).filter(Boolean);
-  return out.length ? out : void 0;
-}
-async function enqueueStopTask(context, target, queue = "tasks", allowanceMs = 5e3) {
+async function enqueueStopTask(context, serviceGroup, queueName = "tasks", allowanceMs = 5e3) {
   return enqueueTask(context, {
-    queue,
-    target,
-    task: "stopRunner",
+    queueName,
+    name: "stopRunner",
     params: { allowanceMs },
-    priority: 1e6
+    priority: 0,
+    serviceGroup
   });
 }
 async function signalRunningTasksStop(context, runningTaskInstances, allowanceMs) {
@@ -1916,19 +2882,21 @@ async function signalRunningTasksStop(context, runningTaskInstances, allowanceMs
   context.emitter.emit("stop", allowanceMs);
 }
 async function executeClaimedTask(context, tasksTable, historyTable, row, registry, runningTaskInstances) {
-  const db = getDb2(context);
-  const taskName = row.task;
+  const db = getDb3(context);
+  const taskName = row.name;
   const TaskClass = registry.get(taskName);
-  const { paused_at: _pausedAt, ...rowForHistory } = row;
   if (!TaskClass) {
     const err = { message: `Unknown task "${taskName}"` };
-    await db(historyTable).insert({
-      ...rowForHistory,
-      completed_at: /* @__PURE__ */ new Date(),
-      success: false,
-      params: toJsonColumn(row.params),
-      results: toJsonColumn(err)
-    });
+    await db(historyTable).insert(
+      taskHistoryInsertFromQueueRow(row, {
+        completed_at: /* @__PURE__ */ new Date(),
+        success: false,
+        status: "failed",
+        status_changed_at: db.fn.now(),
+        params: toJsonColumn(row.params),
+        results: toJsonColumn(err)
+      })
+    );
     if (row.schedule) {
       await db(tasksTable).where({ id: row.id }).update({
         started_at: null,
@@ -1936,7 +2904,8 @@ async function executeClaimedTask(context, tasksTable, historyTable, row, regist
         success: false,
         results: toJsonColumn(err),
         past_due: null,
-        paused_at: db.fn.now(),
+        status: "paused",
+        status_changed_at: db.fn.now(),
         progress: LOCKED_BY_ERROR_MESSAGE
       });
     } else {
@@ -1963,13 +2932,16 @@ async function executeClaimedTask(context, tasksTable, historyTable, row, regist
   } finally {
     runningTaskInstances.delete(row.id);
   }
-  await db(historyTable).insert({
-    ...rowForHistory,
-    completed_at: /* @__PURE__ */ new Date(),
-    success,
-    params: toJsonColumn(row.params),
-    results: toJsonColumn(results)
-  });
+  await db(historyTable).insert(
+    taskHistoryInsertFromQueueRow(row, {
+      completed_at: /* @__PURE__ */ new Date(),
+      success,
+      status: success ? "completed" : "failed",
+      status_changed_at: db.fn.now(),
+      params: toJsonColumn(row.params),
+      results: toJsonColumn(results)
+    })
+  );
   if (!success) {
     const dbName = String(context?.params?.get?.("dbName") || "local");
     const tableName = String(context?.params?.get?.("table") || "tasks");
@@ -1984,19 +2956,32 @@ async function executeClaimedTask(context, tasksTable, historyTable, row, regist
     const rerunCommand = results && typeof results === "object" && results.rerunCommand ? results.rerunCommand : fallbackRecoverCommand;
     appendTaskIpcLog(context, row, {
       level: "error",
-      message: `[tasks] task failed: ${row.task} id=${row.id}. Once problem is fixed, re-run: ${rerunCommand}`,
+      message: `[tasks] task failed: ${row.name} id=${row.id}. Once problem is fixed, re-run: ${rerunCommand}`,
       details: results
     });
   }
   if (row.schedule) {
     if (success) {
+      let nextRunAt = null;
+      try {
+        nextRunAt = nextTimeMatch(row.schedule, /* @__PURE__ */ new Date());
+      } catch (e) {
+        context.logger?.warn?.(`[tasks] nextTimeMatch after success for task ${row.id}: ${e?.message ?? String(e)}`);
+      }
       await db(tasksTable).where({ id: row.id }).update({
         started_at: null,
         completed_at: /* @__PURE__ */ new Date(),
         success,
         results: toJsonColumn(results),
         progress: null,
-        past_due: null
+        past_due: null,
+        status: "idle",
+        status_changed_at: db.fn.now(),
+        next_run_at: nextRunAt,
+        // Claim overwrites these; clear so idle rows stay “any worker” (see claimNextRunnableTask).
+        service_name: null,
+        server_name: null,
+        instance_number: null
       });
     } else {
       await db(tasksTable).where({ id: row.id }).update({
@@ -2004,7 +2989,8 @@ async function executeClaimedTask(context, tasksTable, historyTable, row, regist
         completed_at: /* @__PURE__ */ new Date(),
         success,
         results: toJsonColumn(results),
-        paused_at: db.fn.now(),
+        status: "paused",
+        status_changed_at: db.fn.now(),
         progress: LOCKED_BY_ERROR_MESSAGE,
         past_due: null
       });
@@ -2016,208 +3002,401 @@ async function executeClaimedTask(context, tasksTable, historyTable, row, regist
   const stopAllowanceMs = stopRunnerRequested ? Number(results.allowanceMs ?? 5e3) : 0;
   return { stopRunnerRequested, stopAllowanceMs };
 }
-async function claimNextRunnableTask(context, tasksTable, target, registry, scanLimit, taskNames) {
-  const db = getDb2(context);
-  let query = db(tasksTable).whereNull("started_at").whereNull("paused_at").where({ target }).orderByRaw("CASE WHEN past_due IS NULL THEN 1 ELSE 0 END ASC").orderBy([{ column: "priority", order: "desc" }]).orderByRaw("CASE WHEN completed_at IS NULL THEN 0 ELSE 1 END ASC").orderBy([{ column: "completed_at", order: "asc" }, { column: "created_at", order: "asc" }]).limit(scanLimit);
+function shuffleTaskRowsInPlace(rows) {
+  for (let i = rows.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    const t = rows[i];
+    rows[i] = rows[j];
+    rows[j] = t;
+  }
+}
+async function claimNextRunnableTask(context, tasksTable, serviceGroup, registry, scanLimit, taskNames, runnerIdentity) {
+  const db = getDb3(context);
+  let query = db(tasksTable).where({ status: "idle" }).where(function() {
+    this.whereNull("service_group").orWhere({ service_group: serviceGroup });
+  }).orderByRaw("CASE WHEN past_due IS NULL THEN 1 ELSE 0 END ASC").orderBy([{ column: "priority", order: "asc" }]).orderByRaw("CASE WHEN completed_at IS NULL THEN 0 ELSE 1 END ASC").orderBy([{ column: "completed_at", order: "asc" }, { column: "created_at", order: "asc" }]).limit(scanLimit);
   if (taskNames && taskNames.length > 0) {
-    query = query.whereIn("task", taskNames);
+    query = query.whereIn("name", taskNames);
+  }
+  if (runnerIdentity) {
+    query = query.where(function() {
+      this.whereNull("service_name").orWhere({ service_name: runnerIdentity.service_name });
+    }).where(function() {
+      this.whereNull("instance_number").orWhere({ instance_number: runnerIdentity.instance_number });
+    }).where(function() {
+      this.whereNull("server_name").orWhere({ server_name: runnerIdentity.server_name });
+    });
+  } else {
+    query = query.whereNull("service_name").whereNull("instance_number").whereNull("server_name");
   }
   const candidates = await query;
+  shuffleTaskRowsInPlace(candidates);
   for (const row of candidates) {
     if (!row.past_due && row.schedule && !timeMatcher(row.schedule)) {
       continue;
     }
-    const TaskClass = registry.get(row.task);
-    if (TaskClass) {
-      const taskInstance = new TaskClass(context, row);
-      const reason = taskInstance.cantRunReason ? await taskInstance.cantRunReason() : null;
-      if (reason) {
-        if (!row.past_due) {
-          await db(tasksTable).where({ id: row.id }).update({
-            past_due: db.fn.now(),
-            progress: String(reason)
-          });
-        }
-        continue;
+    const TaskClass = registry.get(row.name);
+    if (!TaskClass) {
+      continue;
+    }
+    const taskInstance = new TaskClass(context, row);
+    const reason = taskInstance.cantRunReason ? await taskInstance.cantRunReason() : null;
+    if (reason) {
+      if (!row.past_due) {
+        await db(tasksTable).where({ id: row.id }).update({
+          past_due: db.fn.now(),
+          progress: String(reason)
+        });
       }
+      continue;
     }
-    const updated = await db(tasksTable).where({ id: row.id }).whereNull("started_at").whereNull("paused_at").update({ started_at: db.fn.now() }).returning("*");
+    const claimPatch = {
+      started_at: db.fn.now(),
+      status: "running",
+      status_changed_at: db.fn.now()
+    };
+    if (runnerIdentity) {
+      claimPatch.service_name = runnerIdentity.service_name;
+      claimPatch.server_name = runnerIdentity.server_name;
+      claimPatch.instance_number = runnerIdentity.instance_number;
+    }
+    const updated = await db(tasksTable).where({ id: row.id, status: "idle" }).update(claimPatch).returning("*");
     const claimed = Array.isArray(updated) ? updated[0] : null;
     if (claimed) return claimed;
   }
   return null;
 }
 async function runTasksLoop(context, options) {
-  const queue = options.queue ?? "tasks";
+  const queueName = options.queueName ?? "tasks";
   const target = options.target;
   const pollMs = options.pollMs ?? 1e3;
-  const maxParallel = options.maxParallel ?? 1;
+  const claimJitterMs = options.claimJitterMs ?? 0;
+  const maxParallel = options.maxParallel ?? 32;
   const scanLimit = options.scanLimit ?? 100;
   const allowedTasks = normalizeAllowedTasks(options.allowedTasks);
   const registry = normalizeRegistry(options.registry);
-  const { tasksTable, historyTable } = queueToTableNames(queue);
+  const { tasksTable, historyTable } = queueToTableNames(queueName);
   if (!target) throw new Error("runTasksLoop: target is required");
+  context.tasksQueueName = queueName;
   const runningPromises = /* @__PURE__ */ new Set();
   const runningTaskInstances = /* @__PURE__ */ new Map();
   let runningStopControlPromise = null;
   let stopRequested = false;
   let stopAllowanceMs = 5e3;
-  context.__tasksRunnerStop = false;
-  while (!context.isStop() && !stopRequested && !context.__tasksRunnerStop) {
-    if (!runningStopControlPromise) {
-      const claimedStopTask = await claimNextRunnableTask(
-        context,
-        tasksTable,
-        target,
-        registry,
-        10,
-        ["stopRunner", "stop"]
-      );
-      if (claimedStopTask) {
-        runningStopControlPromise = executeClaimedTask(
+  context.tasksRunnerStop = false;
+  let registryReg = null;
+  let registryInterval = null;
+  let runnerIdentity = null;
+  const hbGroup = options.runnerServiceGroup?.trim();
+  if (hbGroup) {
+    const hbIntervalMs = options.runnerHeartbeatIntervalMs ?? 1e4;
+    const staleMs = options.runnerHeartbeatStaleMs ?? 45e3;
+    const defaultMeta = {
+      component: "tasks-runner",
+      allowedTasks: allowedTasks?.length ? allowedTasks.join(",") : "all"
+    };
+    registryReg = await registerInServicesRegistry(context, {
+      queueName,
+      target,
+      serviceGroup: hbGroup,
+      serviceName: options.runnerServiceName,
+      instanceNumber: options.runnerInstanceNumber,
+      staleMs,
+      groupMaxInstances: options.runnerGroupMaxInstances,
+      enforceMaxInstances: options.runnerEnforceMaxInstances ?? true,
+      metadata: options.runnerMetadata ?? defaultMeta
+    });
+    runnerIdentity = {
+      service_name: registryReg.serviceName,
+      server_name: os3.hostname(),
+      instance_number: registryReg.instanceNumber
+    };
+    registryInterval = setInterval(() => {
+      void touchServicesRegistry(context, registryReg).catch((err) => {
+        context.logger.warn?.(`[services-registry] touch failed: ${err?.message ?? String(err)}`);
+      });
+    }, hbIntervalMs);
+  }
+  try {
+    while (!context.isStop() && !stopRequested && context.tasksRunnerStop !== true) {
+      if (!runningStopControlPromise) {
+        const claimedStopTask = await claimNextRunnableTask(
           context,
           tasksTable,
-          historyTable,
-          claimedStopTask,
+          target,
           registry,
-          runningTaskInstances
-        ).then(async (outcome) => {
+          10,
+          ["stopRunner", "stop"],
+          runnerIdentity
+        );
+        if (claimedStopTask) {
+          runningStopControlPromise = executeClaimedTask(
+            context,
+            tasksTable,
+            historyTable,
+            claimedStopTask,
+            registry,
+            runningTaskInstances
+          ).then(async (outcome) => {
+            if (outcome.stopRunnerRequested && !stopRequested) {
+              stopRequested = true;
+              stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
+              context.tasksRunnerStop = true;
+              await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
+            }
+          }).finally(() => {
+            runningStopControlPromise = null;
+          });
+        }
+      }
+      if (claimJitterMs > 0) {
+        await sleepMs(Math.floor(Math.random() * (claimJitterMs + 1)));
+      }
+      while (runningPromises.size < maxParallel) {
+        const claimed = await claimNextRunnableTask(
+          context,
+          tasksTable,
+          target,
+          registry,
+          scanLimit,
+          allowedTasks,
+          runnerIdentity
+        );
+        if (!claimed) break;
+        const p = executeClaimedTask(context, tasksTable, historyTable, claimed, registry, runningTaskInstances).then(async (outcome) => {
           if (outcome.stopRunnerRequested && !stopRequested) {
             stopRequested = true;
             stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
-            context.__tasksRunnerStop = true;
+            context.tasksRunnerStop = true;
             await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
           }
         }).finally(() => {
-          runningStopControlPromise = null;
+          runningPromises.delete(p);
         });
+        runningPromises.add(p);
+      }
+      const wakePromises = [...runningPromises];
+      if (runningStopControlPromise) {
+        wakePromises.push(runningStopControlPromise);
+      }
+      if (wakePromises.length === 0) {
+        await sleepMs(pollMs);
+      } else {
+        const safe = wakePromises.map((p) => p.catch(() => void 0));
+        await Promise.race([sleepMs(pollMs), Promise.race(safe)]);
       }
     }
-    while (runningPromises.size < maxParallel) {
-      const claimed = await claimNextRunnableTask(
-        context,
-        tasksTable,
-        target,
-        registry,
-        scanLimit,
-        allowedTasks
-      );
-      if (!claimed) break;
-      const p = executeClaimedTask(context, tasksTable, historyTable, claimed, registry, runningTaskInstances).then(async (outcome) => {
-        if (outcome.stopRunnerRequested && !stopRequested) {
-          stopRequested = true;
-          stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
-          context.__tasksRunnerStop = true;
-          await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
-        }
-      }).finally(() => {
-        runningPromises.delete(p);
-      });
-      runningPromises.add(p);
+    if (context.isStop() && !stopRequested) {
+      await signalRunningTasksStop(context, runningTaskInstances, 5e3);
     }
-    await sleepMs(pollMs);
-  }
-  if (context.isStop() && !stopRequested) {
-    await signalRunningTasksStop(context, runningTaskInstances, 5e3);
-  }
-  if (runningPromises.size > 0) {
-    if (stopRequested) {
-      await Promise.race([
-        Promise.allSettled(Array.from(runningPromises)),
-        sleepMs(stopAllowanceMs).then(() => {
-          context.logger.warn?.(
-            `[tasks] stop allowance (${stopAllowanceMs}ms) reached; ${runningPromises.size} task(s) still running`
-          );
-        })
-      ]);
-    } else {
-      await Promise.allSettled(Array.from(runningPromises));
+    if (runningPromises.size > 0) {
+      if (stopRequested) {
+        await Promise.race([
+          Promise.allSettled(Array.from(runningPromises)),
+          sleepMs(stopAllowanceMs).then(() => {
+            context.logger.warn?.(
+              `[tasks] stop allowance (${stopAllowanceMs}ms) reached; ${runningPromises.size} task(s) still running`
+            );
+          })
+        ]);
+      } else {
+        await Promise.allSettled(Array.from(runningPromises));
+      }
+    }
+  } finally {
+    if (registryInterval) {
+      clearInterval(registryInterval);
+      registryInterval = null;
+    }
+    if (registryReg) {
+      await unregisterServicesRegistry(context, registryReg).catch((err) => {
+        context.logger.warn?.(`[services-registry] unregister failed: ${err?.message ?? String(err)}`);
+      });
+      registryReg = null;
+      delete context.servicesRegistry;
+      delete context.runnerHeartbeat;
     }
   }
 }
 async function waitForTaskResult(context, taskId, options = {}) {
-  const db = getDb2(context);
-  const queue = options.queue ?? "tasks";
+  const db = getDb3(context);
+  const queueName = options.queueName ?? "tasks";
   const timeoutMs = options.timeoutMs ?? 6e4;
   const pollMs = options.pollMs ?? 500;
-  const { tasksTable, historyTable } = queueToTableNames(queue);
+  const { tasksTable, historyTable } = queueToTableNames(queueName);
   const deadline = Date.now() + timeoutMs;
+  const waitStartedAt = /* @__PURE__ */ new Date();
+  let cachedNameOpid = null;
+  async function historySinceWait(name, opid) {
+    let q = db(historyTable).where({ name }).where("completed_at", ">=", waitStartedAt);
+    if (opid == null || opid === "") {
+      q = q.whereNull("opid");
+    } else {
+      q = q.where({ opid });
+    }
+    return await q.orderBy("completed_at", "desc").first();
+  }
   while (Date.now() <= deadline) {
-    const done = await db(historyTable).where({ id: taskId }).orderBy("created_at", "desc").first();
-    if (done) return done;
+    const legacy = await db(historyTable).where({ id: taskId }).orderBy("created_at", "desc").first();
+    if (legacy) {
+      return legacy;
+    }
     const pending = await db(tasksTable).where({ id: taskId }).first();
-    if (!pending) {
-      const maybeDone = await db(historyTable).where({ id: taskId }).orderBy("created_at", "desc").first();
-      return maybeDone ?? null;
+    if (pending) {
+      cachedNameOpid = { name: pending.name, opid: pending.opid };
+      const done = await historySinceWait(pending.name, pending.opid);
+      if (done) {
+        return done;
+      }
+    } else if (cachedNameOpid) {
+      const done = await historySinceWait(cachedNameOpid.name, cachedNameOpid.opid);
+      if (done) {
+        return done;
+      }
+      return null;
+    } else {
+      return null;
     }
     await sleepMs(pollMs);
   }
   return null;
 }
 var TasksManager = class _TasksManager {
-  context;
-  queue;
-  target;
-  recreateTaskTables;
-  pollMs;
-  maxParallel;
-  scanLimit;
-  allowedTasks;
-  registry;
+  /**
+   * @param {object} context
+   * @param {{
+   *   queueName?: string,
+   *   target?: string,
+   *   recreateTaskTables?: boolean,
+   *   pollMs?: number,
+   *   claimJitterMs?: number,
+   *   maxParallel?: number,
+   *   scanLimit?: number,
+   *   allowedTasks?: string | string[],
+   *   registry?: TasksRegistry | Record<string, Function>,
+   *   runnerServiceGroup?: string,
+   *   runnerServiceName?: string,
+   *   runnerInstanceNumber?: number,
+   *   runnerHeartbeatIntervalMs?: number,
+   *   runnerHeartbeatStaleMs?: number,
+   *   runnerGroupMaxInstances?: number,
+   *   runnerEnforceMaxInstances?: boolean,
+   *   runnerMetadata?: Record<string, unknown>,
+   * }} [options]
+   */
   constructor(context, options = {}) {
     this.context = context;
-    this.queue = options.queue ?? "tasks";
+    this.queueName = options.queueName ?? "tasks";
     this.target = options.target ?? "localRunner";
     this.recreateTaskTables = options.recreateTaskTables ?? false;
     this.pollMs = options.pollMs ?? 1e3;
+    this.claimJitterMs = options.claimJitterMs ?? 0;
     this.maxParallel = options.maxParallel ?? 1;
     this.scanLimit = options.scanLimit ?? 100;
     this.allowedTasks = normalizeAllowedTasks(options.allowedTasks);
     this.registry = normalizeRegistry(options.registry);
+    this.runnerServiceGroup = options.runnerServiceGroup;
+    this.runnerServiceName = options.runnerServiceName;
+    this.runnerInstanceNumber = options.runnerInstanceNumber;
+    this.runnerHeartbeatIntervalMs = options.runnerHeartbeatIntervalMs;
+    this.runnerHeartbeatStaleMs = options.runnerHeartbeatStaleMs;
+    this.runnerGroupMaxInstances = options.runnerGroupMaxInstances;
+    this.runnerEnforceMaxInstances = options.runnerEnforceMaxInstances;
+    this.runnerMetadata = options.runnerMetadata;
   }
+  /**
+   * Preferred factory: reads defaults from `context.params` (module namespace
+   * `"tasks"`), then overlays explicit `options`. Keeps CLI flags, env vars,
+   * and inline options in one consistent resolver.
+   *
+   * @param {object} context
+   * @param {ConstructorParameters<typeof TasksManager>[1]} [options]
+   * @returns {TasksManager}
+   */
   static init(context, options = {}) {
     const defs = {
       table: "string default tasks",
       target: "string default localRunner",
       recreateTaskTables: "boolean default false",
       pollMs: "number default 1000",
+      claimJitterMs: "number default 0",
       maxParallel: "number default 1",
       scanLimit: "number default 100",
-      allowedTasks: "string"
+      allowedTasks: "string",
+      runnerServiceGroup: "string",
+      runnerServiceName: "string",
+      runnerInstanceNumber: "number",
+      runnerHeartbeatIntervalMs: "number default 10000",
+      runnerHeartbeatStaleMs: "number default 45000",
+      runnerGroupMaxInstances: "number",
+      runnerEnforceMaxInstances: "boolean default true"
     };
-    const discovered = context.params.getAllForModule(defs);
+    const discovered = context.params.getAllForModule("tasks", defs);
     const resolved = {
-      queue: discovered.table,
+      queueName: discovered.table,
       target: discovered.target,
       recreateTaskTables: discovered.recreateTaskTables,
       pollMs: discovered.pollMs,
+      claimJitterMs: discovered.claimJitterMs,
       maxParallel: discovered.maxParallel,
       scanLimit: discovered.scanLimit,
       allowedTasks: discovered.allowedTasks,
+      runnerServiceGroup: discovered.runnerServiceGroup,
+      runnerServiceName: discovered.runnerServiceName,
+      runnerInstanceNumber: discovered.runnerInstanceNumber,
+      runnerHeartbeatIntervalMs: discovered.runnerHeartbeatIntervalMs,
+      runnerHeartbeatStaleMs: discovered.runnerHeartbeatStaleMs,
+      runnerGroupMaxInstances: discovered.runnerGroupMaxInstances,
+      runnerEnforceMaxInstances: discovered.runnerEnforceMaxInstances,
       ...options
     };
     return new _TasksManager(context, resolved);
   }
+  /**
+   * Idempotently ensure the three backing tables exist for this queue.
+   *
+   * @param {{ recreate?: boolean }} [options]
+   * @returns {Promise<void>}
+   */
   async ensureTaskTables(options = {}) {
     await ensureTaskTables(this.context, {
-      queue: this.queue,
+      queueName: this.queueName,
       recreate: options.recreate ?? this.recreateTaskTables
     });
   }
+  /**
+   * Start the runner loop using this manager's resolved config. Per-call
+   * options override the stored defaults, but `runnerMetadata` still falls
+   * through when omitted.
+   *
+   * @param {Partial<ConstructorParameters<typeof TasksManager>[1]>} [options]
+   * @returns {Promise<void>}
+   */
   async runTasksLoop(options = {}) {
     await runTasksLoop(this.context, {
-      queue: options.queue ?? this.queue,
+      queueName: options.queueName ?? this.queueName,
       target: options.target ?? this.target,
       pollMs: options.pollMs ?? this.pollMs,
+      claimJitterMs: options.claimJitterMs ?? this.claimJitterMs,
       maxParallel: options.maxParallel ?? this.maxParallel,
       scanLimit: options.scanLimit ?? this.scanLimit,
       allowedTasks: options.allowedTasks ?? this.allowedTasks,
-      registry: options.registry ?? this.registry
+      registry: options.registry ?? this.registry,
+      runnerServiceGroup: options.runnerServiceGroup ?? this.runnerServiceGroup,
+      runnerServiceName: options.runnerServiceName ?? this.runnerServiceName,
+      runnerInstanceNumber: options.runnerInstanceNumber ?? this.runnerInstanceNumber,
+      runnerHeartbeatIntervalMs: options.runnerHeartbeatIntervalMs ?? this.runnerHeartbeatIntervalMs,
+      runnerHeartbeatStaleMs: options.runnerHeartbeatStaleMs ?? this.runnerHeartbeatStaleMs,
+      runnerGroupMaxInstances: options.runnerGroupMaxInstances ?? this.runnerGroupMaxInstances,
+      runnerEnforceMaxInstances: options.runnerEnforceMaxInstances ?? this.runnerEnforceMaxInstances,
+      runnerMetadata: options.runnerMetadata ?? this.runnerMetadata
     });
   }
 };
 export {
-  TaskMaster,
+  AbstractTask,
+  SERVICE_TASK_NAMES,
+  TaskGetLogs,
   TaskPing,
   TaskSampleProcess,
   TaskShellCommand,
@@ -2227,13 +3406,36 @@ export {
   TasksManager,
   TasksRegistry,
   appendTaskIpcLog,
+  convertPattern,
   defaultTasksRegistry,
   enqueueStopTask,
   enqueueTask,
   ensureTaskTables,
+  flushTaskIpcLogs,
+  ipcFileLogsTableNameForSourceResource,
+  listServicesRegistry as listAliveRunnerHeartbeats,
+  listServicesRegistry,
+  matchesParsedPattern,
+  mergeAllowedTasksWithServiceTasks,
+  nextTimeMatch,
+  normalizeAllowedTasks,
   queueToTableNames,
+  readTaskIpcLogsSnapshot,
+  registerInServicesRegistry,
+  registerInServicesRegistry as registerRunnerHeartbeat,
+  resolveAsterisks,
+  resolveIpcFileLogsDir,
+  resolveRanges,
+  resolveSteps,
   runNodeTaskScript,
   runTasksLoop,
+  taskHistoryInsertFromQueueRow,
+  timeMatcher,
+  touchServicesRegistry as touchRunnerHeartbeat,
+  touchServicesRegistry,
+  unregisterServicesRegistry as unregisterRunnerHeartbeat,
+  unregisterServicesRegistry,
+  updateServicesRegistryMetadata,
   updateTaskProgress,
   waitForTaskResult
 };