@nmakarov/cli-toolkit 0.18.0 → 0.21.0

package/dist/cli-runner.cjs

@@ -924,11 +924,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({
@@ -1118,7 +1118,7 @@ var init_screen = __esm({
 });
 
 // src/scripts/cli-runner.ts
-var import_node_path = __toESM(require("path"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 
 // src/args/index.ts
@@ -1944,7 +1944,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();
@@ -2020,6 +2020,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);
@@ -2056,6 +2058,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>/...
    */
@@ -2069,9 +2084,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";
@@ -2922,7 +2937,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;
@@ -3027,6 +3042,12 @@ function toJsonColumn(value) {
   return JSON.stringify(value);
 }
 
+// src/tasks/servicesRegistry.ts
+var import_node_crypto2 = require("crypto");
+var import_promises = require("fs/promises");
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path = __toESM(require("path"), 1);
+
 // src/tasks/taskUtils.ts
 var import_node_crypto = require("crypto");
 function getDb(context) {
@@ -3045,6 +3066,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;
@@ -3081,18 +3108,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();
@@ -3115,10 +3130,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`);
     });
   }
 }
@@ -3129,6 +3158,225 @@ 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 import_node_path.default.join(identityDir, `${safeQ}_${safeG}.json`);
+}
+async function readIdentityFile(filePath) {
+  try {
+    const text = await (0, import_promises.readFile)(filePath, "utf8");
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+async function writeIdentityFile(filePath, data) {
+  await (0, import_promises.mkdir)(import_node_path.default.dirname(filePath), { recursive: true });
+  await (0, import_promises.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() : (0, import_node_crypto2.randomUUID)();
+  identity.instanceId = instanceId;
+  await writeIdentityFile(identityPath, identity);
+  const hostname = import_node_os.default.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 = import_node_os.default.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
 var import_fs4 = __toESM(require("fs"), 1);
 var import_path4 = __toESM(require("path"), 1);
@@ -4497,8 +4745,8 @@ var TaskShellCommand = class extends TaskMaster {
 };
 
 // src/tasks/coreTasks/TaskSystemInfo.ts
-var import_node_os = __toESM(require("os"), 1);
-var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_os2 = __toESM(require("os"), 1);
+var import_promises2 = __toESM(require("fs/promises"), 1);
 function toGb(valueBytes) {
   return `${(valueBytes / 1024 ** 3).toFixed(2)} GB`;
 }
@@ -4506,7 +4754,7 @@ function toMb(valueBytes) {
   return `${(valueBytes / 1024 ** 2).toFixed(2)} MB`;
 }
 async function getDiskStats() {
-  const stats = await import_promises.default.statfs("/");
+  const stats = await import_promises2.default.statfs("/");
   const total = Number(stats.bsize) * Number(stats.blocks);
   const free = Number(stats.bsize) * Number(stats.bavail);
   const used = total - free;
@@ -4519,10 +4767,10 @@ async function getDiskStats() {
 var TaskSystemInfo = class extends TaskMaster {
   async run() {
     try {
-      const totalMemory = import_node_os.default.totalmem();
-      const freeMemory = import_node_os.default.freemem();
+      const totalMemory = import_node_os2.default.totalmem();
+      const freeMemory = import_node_os2.default.freemem();
       const usedMemory = totalMemory - freeMemory;
-      const cpus = import_node_os.default.cpus();
+      const cpus = import_node_os2.default.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;
@@ -4548,10 +4796,10 @@ var TaskSystemInfo = class extends TaskMaster {
           utilization: cpuUtilization
         },
         runtime: {
-          platform: import_node_os.default.platform(),
-          arch: import_node_os.default.arch(),
-          uptimeSec: import_node_os.default.uptime(),
-          hostname: import_node_os.default.hostname()
+          platform: import_node_os2.default.platform(),
+          arch: import_node_os2.default.arch(),
+          uptimeSec: import_node_os2.default.uptime(),
+          hostname: import_node_os2.default.hostname()
         }
       };
       this.context.logger.info?.(`[TaskSystemInfo] collected system metrics (${this.task.id})`);
@@ -4654,7 +4902,7 @@ var import_node_child_process2 = require("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.");
@@ -4689,7 +4937,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;
@@ -4790,7 +5038,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);
@@ -4836,25 +5084,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;
@@ -4862,49 +5161,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;
     }
   }
 }
@@ -4918,6 +5209,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";
@@ -4928,6 +5227,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 = {
@@ -4937,7 +5244,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 = {
@@ -4948,6 +5262,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);
@@ -4966,7 +5287,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
     });
   }
 };
@@ -4977,7 +5306,7 @@ var defs = {
   tasksModule: "string"
 };
 async function loadTasksModule(modulePath) {
-  const absolute = import_node_path.default.isAbsolute(modulePath) ? modulePath : import_node_path.default.resolve(process.cwd(), modulePath);
+  const absolute = import_node_path2.default.isAbsolute(modulePath) ? modulePath : import_node_path2.default.resolve(process.cwd(), modulePath);
   const imported = await import((0, import_node_url.pathToFileURL)(absolute).href);
   if (!imported.tasksRegistry || typeof imported.tasksRegistry !== "object") {
     throw new Error(`tasksModule "${modulePath}" must export "tasksRegistry" object`);