@nmakarov/cli-toolkit 0.18.0 → 0.21.0

package/dist/cli-runner.js

@@ -907,11 +907,11 @@ function buildBreadcrumb(parts) {
   if (parts.length === 1) return parts[0];
   return parts.slice(1).map((part) => `\u2190  ${part}`).join("  ");
 }
-function buildDetailBreadcrumb(path5, suffix = "") {
-  if (path5.length <= 1) {
-    return suffix ? `\u2190  ${suffix}` : path5[0] || "";
+function buildDetailBreadcrumb(path6, suffix = "") {
+  if (path6.length <= 1) {
+    return suffix ? `\u2190  ${suffix}` : path6[0] || "";
   }
-  const breadcrumb = buildBreadcrumb(path5);
+  const breadcrumb = buildBreadcrumb(path6);
   return suffix ? `${breadcrumb} ${suffix}` : breadcrumb;
 }
 var init_utils = __esm({
@@ -1101,7 +1101,7 @@ var init_screen = __esm({
 });
 
 // src/scripts/cli-runner.ts
-import path4 from "path";
+import path5 from "path";
 import { pathToFileURL } from "url";
 
 // src/args/index.ts
@@ -1927,7 +1927,7 @@ var Params = class _Params {
         throw new ParamError(`default value "${defValObj.value}" type mismatch`);
       }
       type = type.default(defValObj.value);
-    } else if (str.match(/required/)) {
+    } else if (str.match(/\s*required\s*/)) {
       type = type.required();
     } else {
       type = type.optional();
@@ -2003,6 +2003,8 @@ var Params = class _Params {
   /**
    * Get all parameters from definitions (main script).
    * Same as getAllForModule("script", defs). Processes left-to-right for cross-parameter references.
+   * Libraries should use {@link getAllForModule} with an explicit module name (or {@link runWithModule}
+   * around {@link get}) so --showUsedParams groups usage correctly.
    */
   getAll(defs2) {
     return this.getAllForModule("script", defs2);
@@ -2039,6 +2041,19 @@ var Params = class _Params {
       this._currentModule = prev;
     }
   }
+  /**
+   * Run a callback with {@link _currentModule} set so single {@link get} calls are tracked
+   * under the same module (for --showUsedParams / getFiguredByModule).
+   */
+  runWithModule(moduleName, fn) {
+    const prev = this._currentModule;
+    this._currentModule = moduleName;
+    try {
+      return fn();
+    } finally {
+      this._currentModule = prev;
+    }
+  }
   /**
    * Infer module name from call stack: first caller outside params/index gives path like .../src/<moduleName>/...
    */
@@ -2052,9 +2067,9 @@ var Params = class _Params {
       if (!parenMatch) continue;
       const parts = parenMatch[1].split(":");
       if (parts.length < 3) continue;
-      const path5 = parts.slice(0, -2).join(":").replace(/^file:\/\//, "");
-      if (!path5 || path5.includes(paramsIndexPath)) continue;
-      const srcMatch = path5.match(/[/\\]src[/\\]([^/\\]+)(?:[/\\]|$)/);
+      const path6 = parts.slice(0, -2).join(":").replace(/^file:\/\//, "");
+      if (!path6 || path6.includes(paramsIndexPath)) continue;
+      const srcMatch = path6.match(/[/\\]src[/\\]([^/\\]+)(?:[/\\]|$)/);
       if (srcMatch) return srcMatch[1];
     }
     return "script";
@@ -2905,7 +2920,7 @@ async function dbFindAndConnect(context, dbNameOrConnectionString) {
       dbConnectionString: "string",
       dbProfile: "boolean default false"
     };
-    const paramsConfig = context.params.getAllForModule(defs2);
+    const paramsConfig = context.params.getAll(defs2);
     dbName = paramsConfig.dbName;
     dbConnectionString = paramsConfig.dbConnectionString;
     dbProfile = paramsConfig.dbProfile;
@@ -3010,6 +3025,12 @@ function toJsonColumn(value) {
   return JSON.stringify(value);
 }
 
+// src/tasks/servicesRegistry.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import os from "os";
+import path3 from "path";
+
 // src/tasks/taskUtils.ts
 import { randomUUID } from "crypto";
 function getDb(context) {
@@ -3028,6 +3049,12 @@ function queueToTableNames(queue) {
     historyTable: `${queue}_history`
   };
 }
+function servicesRegistryTable(queue) {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(queue)) {
+    throw new Error(`Invalid queue name "${queue}". Use letters, numbers, underscore only.`);
+  }
+  return `${queue}_services_registry`;
+}
 async function ensureTaskTables(context, options = {}) {
   const queue = options.queue ?? "tasks";
   const recreate = options.recreate ?? false;
@@ -3064,18 +3091,6 @@ async function ensureTaskTables(context, options = {}) {
       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);
-    });
-  }
   if (needsHistory) {
     await db.schema.createTable(historyTable, (t) => {
       t.uuid("id").notNullable();
@@ -3098,10 +3113,24 @@ async function ensureTaskTables(context, options = {}) {
       t.index(["task", "created_at"], `${historyTable}_task_created_idx`);
     });
   }
-  const historyHasOpid = await db.schema.hasColumn(historyTable, "opid");
-  if (!historyHasOpid) {
-    await db.schema.alterTable(historyTable, (t) => {
-      t.text("opid");
+  const registryTable = servicesRegistryTable(queue);
+  const needsRegistry = !await db.tableExists(registryTable);
+  if (needsRegistry) {
+    await db.schema.createTable(registryTable, (t) => {
+      t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
+      t.uuid("instance_id").notNullable().unique();
+      t.text("queue").notNullable();
+      t.text("service_group").notNullable();
+      t.text("service_name").notNullable();
+      t.text("target").notNullable();
+      t.text("hostname");
+      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", "service_name"], `${registryTable}_queue_service_name_uniq`);
+      t.index(["queue", "service_group", "last_seen_at"], `${registryTable}_queue_group_seen_idx`);
+      t.index(["queue", "last_seen_at"], `${registryTable}_queue_seen_idx`);
     });
   }
 }
@@ -3112,9 +3141,228 @@ async function updateTaskProgress(context, tasksTable, taskId, progress) {
   });
 }
 
+// src/tasks/servicesRegistry.ts
+function getDb2(context) {
+  const db = context.db;
+  if (!db) {
+    throw new Error("Services registry requires context.db");
+  }
+  return db;
+}
+var DEFAULT_GROUP_MAX_INSTANCES = {
+  intake: 1,
+  harvest: 1,
+  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 identityFilePath(identityDir, queue, serviceGroup) {
+  const safeQ = sanitizeNamePart(queue);
+  const safeG = sanitizeNamePart(serviceGroup);
+  return path3.join(identityDir, `${safeQ}_${safeG}.json`);
+}
+async function readIdentityFile(filePath) {
+  try {
+    const text = await readFile(filePath, "utf8");
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+async function writeIdentityFile(filePath, data) {
+  await mkdir(path3.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+}
+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, queue, serviceGroup, staleMs, excludeInstanceId) {
+  const cutoff = new Date(Date.now() - staleMs);
+  let q = db(registryTable).where({ queue, service_group: serviceGroup }).where("last_seen_at", ">", cutoff);
+  if (excludeInstanceId) {
+    q = q.whereNot("instance_id", excludeInstanceId);
+  }
+  const row = await q.count("id as count").first();
+  return Number(row?.count ?? 0);
+}
+function isUniqueViolation(error) {
+  const code = error?.code ?? error?.errno;
+  return code === "23505" || String(error?.message || "").includes("duplicate key");
+}
+async function registerInServicesRegistry(context, options) {
+  const db = getDb2(context);
+  const registryTable = servicesRegistryTable(options.queue);
+  const serviceGroup = options.serviceGroup.trim();
+  if (!serviceGroup) {
+    throw new Error("registerInServicesRegistry: serviceGroup is required");
+  }
+  const identityPath = identityFilePath(options.identityDir, options.queue, serviceGroup);
+  let identity = await readIdentityFile(identityPath);
+  let instanceId = typeof identity.instanceId === "string" && identity.instanceId.trim() ? identity.instanceId.trim() : randomUUID2();
+  identity.instanceId = instanceId;
+  await writeIdentityFile(identityPath, identity);
+  const hostname = os.hostname();
+  const pid = typeof process.pid === "number" ? process.pid : null;
+  const meta = toJsonColumn(options.metadata ?? null);
+  const existing = await db(registryTable).where({ instance_id: instanceId }).first();
+  if (existing) {
+    await db(registryTable).where({ instance_id: instanceId }).update({
+      target: options.target,
+      hostname,
+      pid,
+      metadata: meta,
+      last_seen_at: db.fn.now()
+    });
+    const serviceName = String(existing.service_name);
+    identity.serviceName = serviceName;
+    await writeIdentityFile(identityPath, identity);
+    const reg = {
+      instanceId,
+      serviceName,
+      serviceGroup,
+      queue: options.queue,
+      target: options.target,
+      rowId: String(existing.id)
+    };
+    context.servicesRegistry = reg;
+    context.runnerHeartbeat = reg;
+    context.logger.info?.(
+      `[services-registry] resumed instance_id=${instanceId} name=${serviceName} group=${serviceGroup} queue=${options.queue}`
+    );
+    return {
+      instanceId,
+      serviceName,
+      serviceGroup,
+      queue: options.queue,
+      target: options.target,
+      rowId: String(existing.id),
+      registryTable
+    };
+  }
+  const maxAllowed = resolveMaxInstances(serviceGroup, options.groupMaxInstances);
+  const aliveOthers = await countAliveInGroup(
+    db,
+    registryTable,
+    options.queue,
+    serviceGroup,
+    options.staleMs,
+    instanceId
+  );
+  if (maxAllowed > 0 && aliveOthers >= maxAllowed) {
+    const msg = `[services-registry] group limit reached for "${serviceGroup}": ${aliveOthers} alive (max ${maxAllowed}, queue=${options.queue}).`;
+    if (options.enforceMaxInstances) {
+      throw new Error(msg);
+    }
+    context.logger.warn?.(`${msg} Starting anyway (runnerEnforceMaxInstances=false).`);
+  }
+  const explicitName = options.serviceName?.trim();
+  const fromFile = typeof identity.serviceName === "string" ? identity.serviceName.trim() : "";
+  const hostBase = sanitizeNamePart(hostname);
+  const groupBase = sanitizeNamePart(serviceGroup);
+  const baseCandidates = [];
+  if (explicitName) baseCandidates.push(sanitizeNamePart(explicitName));
+  if (fromFile) baseCandidates.push(sanitizeNamePart(fromFile));
+  baseCandidates.push(`${groupBase}-${hostBase}`);
+  baseCandidates.push(groupBase);
+  function* eachServiceNameCandidate(bases) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const rawBase of bases) {
+      const base = sanitizeNamePart(rawBase);
+      if (!base) continue;
+      const seq = [base];
+      for (let n = 2; n <= 500; n++) seq.push(`${base}-${n}`);
+      for (const c of seq) {
+        if (seen.has(c)) continue;
+        seen.add(c);
+        yield c;
+      }
+    }
+  }
+  let inserted;
+  for (const candidate of eachServiceNameCandidate(baseCandidates)) {
+    try {
+      const rows = await db(registryTable).insert({
+        instance_id: instanceId,
+        queue: options.queue,
+        service_group: serviceGroup,
+        service_name: candidate,
+        target: options.target,
+        hostname,
+        pid,
+        metadata: meta,
+        last_seen_at: db.fn.now()
+      }).returning(["id", "service_name"]);
+      const row = Array.isArray(rows) ? rows[0] : rows;
+      if (row) {
+        inserted = { id: String(row.id), service_name: String(row.service_name) };
+        break;
+      }
+    } catch (error) {
+      if (!isUniqueViolation(error)) {
+        throw error;
+      }
+    }
+  }
+  if (!inserted) {
+    throw new Error(
+      `[services-registry] could not allocate a unique service_name for group=${serviceGroup} queue=${options.queue} (too many collisions).`
+    );
+  }
+  identity.serviceName = inserted.service_name;
+  await writeIdentityFile(identityPath, identity);
+  const regNew = {
+    instanceId,
+    serviceName: inserted.service_name,
+    serviceGroup,
+    queue: options.queue,
+    target: options.target,
+    rowId: inserted.id
+  };
+  context.servicesRegistry = regNew;
+  context.runnerHeartbeat = regNew;
+  context.logger.info?.(
+    `[services-registry] registered instance_id=${instanceId} name=${inserted.service_name} group=${serviceGroup} queue=${options.queue} target=${options.target}`
+  );
+  return {
+    instanceId,
+    serviceName: inserted.service_name,
+    serviceGroup,
+    queue: options.queue,
+    target: options.target,
+    rowId: inserted.id,
+    registryTable
+  };
+}
+async function touchServicesRegistry(context, registration) {
+  const db = getDb2(context);
+  const hostname = os.hostname();
+  const pid = typeof process.pid === "number" ? process.pid : null;
+  await db(registration.registryTable).where({ instance_id: registration.instanceId }).update({
+    last_seen_at: db.fn.now(),
+    hostname,
+    pid
+  });
+}
+async function unregisterServicesRegistry(context, registration) {
+  const db = getDb2(context);
+  await db(registration.registryTable).where({ instance_id: registration.instanceId }).delete();
+  context.logger.info?.(`[services-registry] unregistered name=${registration.serviceName} instance_id=${registration.instanceId}`);
+}
+
 // src/filedatabase/index.ts
 import fs3 from "fs";
-import path3 from "path";
+import path4 from "path";
 
 // src/filedatabase/serializers.ts
 function detectDataType(data) {
@@ -3241,7 +3489,7 @@ var FileDatabase = class _FileDatabase {
     if (this.versioned && version) {
       parts.push(version);
     }
-    return path3.resolve(...parts);
+    return path4.resolve(...parts);
   }
   /**
    * Set current version and version folder
@@ -3278,7 +3526,7 @@ var FileDatabase = class _FileDatabase {
     this.currentFileNumber = 0;
     const versions = await this.getVersions();
     while (versions.length > this.maxVersions) {
-      const versionToDelete = path3.resolve(this.getDestinationPath(), versions.shift());
+      const versionToDelete = path4.resolve(this.getDestinationPath(), versions.shift());
       this.logger.silly?.(`[FileDatabase] Deleting old version: ${versionToDelete}`);
       await fs3.promises.rm(versionToDelete, { recursive: true, force: true });
     }
@@ -3297,7 +3545,7 @@ var FileDatabase = class _FileDatabase {
       await ensurePath(destPath);
       const items = await fs3.promises.readdir(destPath);
       const versions = items.filter((item) => {
-        const itemPath = path3.join(destPath, item);
+        const itemPath = path4.join(destPath, item);
         const stat = fs3.statSync(itemPath);
         return stat.isDirectory() && isTimestampFolder(item);
       });
@@ -3354,7 +3602,7 @@ var FileDatabase = class _FileDatabase {
     const items = await fs3.promises.readdir(tablePath);
     if (items.includes("metadata.json")) {
       const metadata = JSON.parse(
-        await fs3.promises.readFile(path3.join(tablePath, "metadata.json"), "utf8")
+        await fs3.promises.readFile(path4.join(tablePath, "metadata.json"), "utf8")
       );
       return {
         versioned: false,
@@ -3363,13 +3611,13 @@ var FileDatabase = class _FileDatabase {
       };
     }
     const versionFolders = items.filter((item) => {
-      const itemPath = path3.join(tablePath, item);
+      const itemPath = path4.join(tablePath, item);
       const stat = fs3.statSync(itemPath);
       return stat.isDirectory() && isTimestampFolder(item);
     });
     if (versionFolders.length > 0) {
       const latestVersion = versionFolders.sort().pop();
-      const versionMetadataPath = path3.join(tablePath, latestVersion, "metadata.json");
+      const versionMetadataPath = path4.join(tablePath, latestVersion, "metadata.json");
       return {
         versioned: true,
         hasMetadata: fs3.existsSync(versionMetadataPath),
@@ -3390,7 +3638,7 @@ var FileDatabase = class _FileDatabase {
    * Load metadata from JSON file
    */
   async loadMetadataJson(version) {
-    const metadataFile = path3.join(this.getDestinationPath(), version, "metadata.json");
+    const metadataFile = path4.join(this.getDestinationPath(), version, "metadata.json");
     if (fs3.existsSync(metadataFile)) {
       try {
         const rawData = await fs3.promises.readFile(metadataFile, "utf8");
@@ -3406,7 +3654,7 @@ var FileDatabase = class _FileDatabase {
    * Reads all files to get accurate counts - used when synopsis calculation is needed
    */
   async figureMetadataFromVersionFiles(version) {
-    const versionPath = path3.join(this.getDestinationPath(), version);
+    const versionPath = path4.join(this.getDestinationPath(), version);
     if (!fs3.existsSync(versionPath)) {
       return this.getDefaultMetadata();
     }
@@ -3418,10 +3666,10 @@ var FileDatabase = class _FileDatabase {
     let detectedDataType = null;
     for (let i = 0; i < files.length; i++) {
       const fileName = files[i];
-      const filePath = path3.join(versionPath, fileName);
+      const filePath = path4.join(versionPath, fileName);
       try {
         const rawData = await fs3.promises.readFile(filePath, "utf8");
-        const extension = path3.extname(fileName).toLowerCase();
+        const extension = path4.extname(fileName).toLowerCase();
         let dataType = "text";
         if (extension === ".json") {
           dataType = "json-array";
@@ -3454,7 +3702,7 @@ var FileDatabase = class _FileDatabase {
    * Much faster for large datasets with many files
    */
   async buildMetadataOptimized(version) {
-    const versionPath = path3.join(this.getDestinationPath(), version);
+    const versionPath = path4.join(this.getDestinationPath(), version);
     if (!fs3.existsSync(versionPath)) {
       return this.getDefaultMetadata();
     }
@@ -3470,7 +3718,7 @@ var FileDatabase = class _FileDatabase {
       fileName
     }));
     const firstFile = metadata.files[0];
-    const firstFilePath = path3.join(versionPath, firstFile.fileName);
+    const firstFilePath = path4.join(versionPath, firstFile.fileName);
     const firstFileRaw = await fs3.promises.readFile(firstFilePath, "utf8");
     let firstFileData;
     try {
@@ -3487,7 +3735,7 @@ var FileDatabase = class _FileDatabase {
       }
       if (files.length > 1) {
         const lastFile = metadata.files[metadata.files.length - 1];
-        const lastFilePath = path3.join(versionPath, lastFile.fileName);
+        const lastFilePath = path4.join(versionPath, lastFile.fileName);
         const lastFileRaw = await fs3.promises.readFile(lastFilePath, "utf8");
         const lastFileData = deserializeData(lastFileRaw, metadata.dataType);
         lastFile.recordsCount = Array.isArray(lastFileData) ? lastFileData.length : 1;
@@ -3538,9 +3786,9 @@ var FileDatabase = class _FileDatabase {
       if (!this.currentVersion) {
         return;
       }
-      metadataFile = path3.join(this.getDestinationPath(), this.currentVersion, "metadata.json");
+      metadataFile = path4.join(this.getDestinationPath(), this.currentVersion, "metadata.json");
     } else {
-      metadataFile = path3.join(this.getDestinationPath(), "metadata.json");
+      metadataFile = path4.join(this.getDestinationPath(), "metadata.json");
     }
     await fs3.promises.writeFile(metadataFile, JSON.stringify(metadataToSave, null, 4), "utf8");
   }
@@ -3603,7 +3851,7 @@ var FileDatabase = class _FileDatabase {
       }
     }
     if (!Array.isArray(data) && !forceNewFile) {
-      const lastFileExtension = path3.extname(lastFile.fileName);
+      const lastFileExtension = path4.extname(lastFile.fileName);
       const expectedExtension = `.${getFileExtension(incomingDataType)}`;
       if (lastFileExtension !== expectedExtension) {
         if (lastFileRecordsCount > 0) {
@@ -3613,7 +3861,7 @@ var FileDatabase = class _FileDatabase {
         }
       }
     } else if (!Array.isArray(data) && forceNewFile) {
-      const lastFileExtension = path3.extname(lastFile.fileName);
+      const lastFileExtension = path4.extname(lastFile.fileName);
       const expectedExtension = `.${getFileExtension(incomingDataType)}`;
       if (lastFileExtension !== expectedExtension) {
         lastFile.fileName = `${this.currentFileNumber.toString().padStart(6, "0")}.${getFileExtension(incomingDataType)}`;
@@ -3703,7 +3951,7 @@ var FileDatabase = class _FileDatabase {
    */
   async safeWrite(filePath, data) {
     const serializedData = serializeData(data);
-    const dir = path3.dirname(filePath);
+    const dir = path4.dirname(filePath);
     const requiredBytes = Buffer.byteLength(serializedData, "utf8");
     const freeBytes = getFreeDiskSpace(dir);
     if (freeBytes !== null) {
@@ -3748,7 +3996,7 @@ var FileDatabase = class _FileDatabase {
       } else {
         await ensurePath(this.getDestinationPath());
         if (this.useMetadata === true) {
-          const metadataPath = path3.join(this.getDestinationPath(), "metadata.json");
+          const metadataPath = path4.join(this.getDestinationPath(), "metadata.json");
           if (fs3.existsSync(metadataPath)) {
             try {
               const rawData = await fs3.promises.readFile(metadataPath, "utf8");
@@ -3801,7 +4049,7 @@ var FileDatabase = class _FileDatabase {
         }
         if (this.useMetadata) {
           const destPath = this.getDestinationPath();
-          const metadataPath = path3.join(destPath, "metadata.json");
+          const metadataPath = path4.join(destPath, "metadata.json");
           if (fs3.existsSync(metadataPath)) {
             try {
               const rawData = await fs3.promises.readFile(metadataPath, "utf8");
@@ -3837,7 +4085,7 @@ var FileDatabase = class _FileDatabase {
     if (options.filename) {
       const destPath2 = this.getDestinationPath();
       await ensurePath(destPath2);
-      const filePath = path3.join(destPath2, options.filename);
+      const filePath = path4.join(destPath2, options.filename);
       await this.safeWrite(filePath, data);
       return;
     }
@@ -3886,11 +4134,11 @@ var FileDatabase = class _FileDatabase {
     const forceNewFile = hasCustomMetadata && targetFileIndex === null;
     let { dataToWrite, dataLeftOver, fileName } = this.figureOutDataAndFileToWrite(data, targetFileIndex, forceNewFile);
     const destPath = this.getDestinationPath(this.currentVersion || void 0);
-    await this.safeWrite(path3.join(destPath, fileName), dataToWrite);
+    await this.safeWrite(path4.join(destPath, fileName), dataToWrite);
     this.updateMetadata(dataToWrite, fileName, options.customMetadata);
     while (dataLeftOver && dataLeftOver.length > 0 && targetFileIndex === null) {
       const writeContext = this.figureOutDataAndFileToWrite(dataLeftOver);
-      await this.safeWrite(path3.join(destPath, writeContext.fileName), writeContext.dataToWrite);
+      await this.safeWrite(path4.join(destPath, writeContext.fileName), writeContext.dataToWrite);
       this.updateMetadata(writeContext.dataToWrite, writeContext.fileName, options.customMetadata);
       dataLeftOver = writeContext.dataLeftOver;
     }
@@ -3906,7 +4154,7 @@ var FileDatabase = class _FileDatabase {
     const { version, nextPage = false, pageSize, filename } = options;
     if (filename) {
       const destPath = this.getDestinationPath(version);
-      const filePath = path3.join(destPath, filename);
+      const filePath = path4.join(destPath, filename);
       try {
         const rawData = await fs3.promises.readFile(filePath, "utf8");
         return JSON.parse(rawData);
@@ -3918,7 +4166,7 @@ var FileDatabase = class _FileDatabase {
     const isNonPaginatedData = this.metadata.dataType === "text" || this.metadata.dataType === "xml" || this.metadata.dataType === "json-object";
     if (isNonPaginatedData) {
       const file = this.metadata.files[0];
-      const filePath = path3.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
+      const filePath = path4.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
       try {
         const rawData = await fs3.promises.readFile(filePath, "utf8");
         return deserializeData(rawData, this.metadata.dataType);
@@ -3956,7 +4204,7 @@ var FileDatabase = class _FileDatabase {
     let cumulativeRecords = currentFileOffset;
     for (let i = currentFileIndex; i < this.metadata.files.length && recordsRead < effectivePageSize; i++) {
       const file = this.metadata.files[i];
-      const filePath = path3.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
+      const filePath = path4.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
       try {
         const rawData = await fs3.promises.readFile(filePath, "utf8");
         const fileData = deserializeData(rawData, this.metadata.dataType);
@@ -4000,7 +4248,7 @@ var FileDatabase = class _FileDatabase {
    * Returns data file names (.json, .txt, .xml) excluding metadata.json.
    */
   async listFilenames() {
-    const destPath = this.versioned && this.currentVersion ? path3.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    const destPath = this.versioned && this.currentVersion ? path4.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
     try {
       const entries = await fs3.promises.readdir(destPath, { withFileTypes: true });
       return entries.filter((e) => e.isFile() && e.name !== "metadata.json" && /\.(json|txt|xml)$/i.test(e.name)).map((e) => e.name);
@@ -4014,8 +4262,8 @@ var FileDatabase = class _FileDatabase {
    * Use with listFilenames() to manage individual files.
    */
   async removeFile(filename) {
-    const destPath = this.versioned && this.currentVersion ? path3.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
-    const filePath = path3.join(destPath, filename);
+    const destPath = this.versioned && this.currentVersion ? path4.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    const filePath = path4.join(destPath, filename);
     try {
       await fs3.promises.unlink(filePath);
     } catch (err) {
@@ -4041,7 +4289,7 @@ var FileDatabase = class _FileDatabase {
     this.metadata.files.splice(idx, 1);
     this.metadata.totalRecords = Math.max(0, (this.metadata.totalRecords || 0) - recordsCount);
     const destPath = this.getDestinationPath();
-    const filePath = path3.join(destPath, filename);
+    const filePath = path4.join(destPath, filename);
     try {
       await fs3.promises.unlink(filePath);
     } catch (err) {
@@ -4097,7 +4345,7 @@ var FileDatabase = class _FileDatabase {
         });
         if (matches) {
           const destPath = this.getDestinationPath();
-          const filePath = path3.join(destPath, fileEntry.fileName);
+          const filePath = path4.join(destPath, fileEntry.fileName);
           const fileData = await fs3.promises.readFile(filePath, "utf8");
           const data = deserializeData(fileData, metadata.dataType || "json-object");
           results.push({
@@ -4120,7 +4368,7 @@ var FileDatabase = class _FileDatabase {
           });
           if (matches) {
             const destPath = this.getDestinationPath(version);
-            const filePath = path3.join(destPath, fileEntry.fileName);
+            const filePath = path4.join(destPath, fileEntry.fileName);
             const fileData = await fs3.promises.readFile(filePath, "utf8");
             const data = deserializeData(fileData, metadata.dataType || "json-object");
             results.push({
@@ -4480,7 +4728,7 @@ var TaskShellCommand = class extends TaskMaster {
 };
 
 // src/tasks/coreTasks/TaskSystemInfo.ts
-import os from "os";
+import os2 from "os";
 import fs4 from "fs/promises";
 function toGb(valueBytes) {
   return `${(valueBytes / 1024 ** 3).toFixed(2)} GB`;
@@ -4502,10 +4750,10 @@ async function getDiskStats() {
 var TaskSystemInfo = class extends TaskMaster {
   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;
@@ -4531,10 +4779,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})`);
@@ -4637,7 +4885,7 @@ import { spawn as spawn2 } from "child_process";
 // src/tasks/index.ts
 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.");
@@ -4672,7 +4920,7 @@ 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 db = getDb3(context);
   const taskName = row.task;
   const TaskClass = registry.get(taskName);
   const { paused_at: _pausedAt, ...rowForHistory } = row;
@@ -4773,7 +5021,7 @@ async function executeClaimedTask(context, tasksTable, historyTable, row, regist
   return { stopRunnerRequested, stopAllowanceMs };
 }
 async function claimNextRunnableTask(context, tasksTable, target, registry, scanLimit, taskNames) {
-  const db = getDb2(context);
+  const db = getDb3(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);
   if (taskNames && taskNames.length > 0) {
     query = query.whereIn("task", taskNames);
@@ -4819,25 +5067,76 @@ async function runTasksLoop(context, options) {
   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(
+  let registryReg = null;
+  let registryInterval = null;
+  const hbGroup = options.runnerServiceGroup?.trim();
+  if (hbGroup) {
+    const identityDir = options.runnerIdentityDir ?? "./data/runner-identities";
+    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, {
+      queue,
+      target,
+      serviceGroup: hbGroup,
+      serviceName: options.runnerServiceName,
+      identityDir,
+      staleMs,
+      groupMaxInstances: options.runnerGroupMaxInstances,
+      enforceMaxInstances: options.runnerEnforceMaxInstances ?? true,
+      metadata: options.runnerMetadata ?? defaultMeta
+    });
+    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) {
+      if (!runningStopControlPromise) {
+        const claimedStopTask = await claimNextRunnableTask(
+          context,
+          tasksTable,
+          target,
+          registry,
+          10,
+          ["stopRunner", "stop"]
+        );
+        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;
+          });
+        }
+      }
+      while (runningPromises.size < maxParallel) {
+        const claimed = await claimNextRunnableTask(
           context,
           tasksTable,
-          historyTable,
-          claimedStopTask,
+          target,
           registry,
-          runningTaskInstances
-        ).then(async (outcome) => {
+          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;
@@ -4845,49 +5144,41 @@ async function runTasksLoop(context, options) {
             await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
           }
         }).finally(() => {
-          runningStopControlPromise = null;
+          runningPromises.delete(p);
         });
+        runningPromises.add(p);
+      }
+      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));
       }
     }
-    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);
+  } finally {
+    if (registryInterval) {
+      clearInterval(registryInterval);
+      registryInterval = null;
     }
-    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 (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;
     }
   }
 }
@@ -4901,6 +5192,14 @@ var TasksManager = class _TasksManager {
   scanLimit;
   allowedTasks;
   registry;
+  runnerServiceGroup;
+  runnerServiceName;
+  runnerIdentityDir;
+  runnerHeartbeatIntervalMs;
+  runnerHeartbeatStaleMs;
+  runnerGroupMaxInstances;
+  runnerEnforceMaxInstances;
+  runnerMetadata;
   constructor(context, options = {}) {
     this.context = context;
     this.queue = options.queue ?? "tasks";
@@ -4911,6 +5210,14 @@ var TasksManager = class _TasksManager {
     this.scanLimit = options.scanLimit ?? 100;
     this.allowedTasks = normalizeAllowedTasks(options.allowedTasks);
     this.registry = normalizeRegistry(options.registry);
+    this.runnerServiceGroup = options.runnerServiceGroup;
+    this.runnerServiceName = options.runnerServiceName;
+    this.runnerIdentityDir = options.runnerIdentityDir;
+    this.runnerHeartbeatIntervalMs = options.runnerHeartbeatIntervalMs;
+    this.runnerHeartbeatStaleMs = options.runnerHeartbeatStaleMs;
+    this.runnerGroupMaxInstances = options.runnerGroupMaxInstances;
+    this.runnerEnforceMaxInstances = options.runnerEnforceMaxInstances;
+    this.runnerMetadata = options.runnerMetadata;
   }
   static init(context, options = {}) {
     const defs2 = {
@@ -4920,7 +5227,14 @@ var TasksManager = class _TasksManager {
       pollMs: "number default 1000",
       maxParallel: "number default 1",
       scanLimit: "number default 100",
-      allowedTasks: "string"
+      allowedTasks: "string",
+      runnerServiceGroup: "string",
+      runnerServiceName: "string",
+      runnerIdentityDir: "string default ./data/runner-identities",
+      runnerHeartbeatIntervalMs: "number default 10000",
+      runnerHeartbeatStaleMs: "number default 45000",
+      runnerGroupMaxInstances: "number",
+      runnerEnforceMaxInstances: "boolean default true"
     };
     const discovered = context.params.getAllForModule(defs2);
     const resolved = {
@@ -4931,6 +5245,13 @@ var TasksManager = class _TasksManager {
       maxParallel: discovered.maxParallel,
       scanLimit: discovered.scanLimit,
       allowedTasks: discovered.allowedTasks,
+      runnerServiceGroup: discovered.runnerServiceGroup,
+      runnerServiceName: discovered.runnerServiceName,
+      runnerIdentityDir: discovered.runnerIdentityDir,
+      runnerHeartbeatIntervalMs: discovered.runnerHeartbeatIntervalMs,
+      runnerHeartbeatStaleMs: discovered.runnerHeartbeatStaleMs,
+      runnerGroupMaxInstances: discovered.runnerGroupMaxInstances,
+      runnerEnforceMaxInstances: discovered.runnerEnforceMaxInstances,
       ...options
     };
     return new _TasksManager(context, resolved);
@@ -4949,7 +5270,15 @@ var TasksManager = class _TasksManager {
       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,
+      runnerIdentityDir: options.runnerIdentityDir ?? this.runnerIdentityDir,
+      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
     });
   }
 };
@@ -4960,7 +5289,7 @@ var defs = {
   tasksModule: "string"
 };
 async function loadTasksModule(modulePath) {
-  const absolute = path4.isAbsolute(modulePath) ? modulePath : path4.resolve(process.cwd(), modulePath);
+  const absolute = path5.isAbsolute(modulePath) ? modulePath : path5.resolve(process.cwd(), modulePath);
   const imported = await import(pathToFileURL(absolute).href);
   if (!imported.tasksRegistry || typeof imported.tasksRegistry !== "object") {
     throw new Error(`tasksModule "${modulePath}" must export "tasksRegistry" object`);