@nmakarov/cli-toolkit 0.18.0 → 0.23.0

package/dist/cli-runner.cjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -30,7 +29,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
-// src/screen/components.ts
+// src/screen/components.js
 function getScreenWidth(maxWidth = null) {
   const terminalWidth = process.stdout.columns || 80;
   const availableWidth = Math.max(20, terminalWidth - 4);
@@ -104,14 +103,13 @@ function ScreenFooter({ lines, textStyle }) {
 }
 var import_react, import_ink;
 var init_components = __esm({
-  "src/screen/components.ts"() {
-    "use strict";
+  "src/screen/components.js"() {
     import_react = require("react");
     import_ink = require("ink");
   }
 });
 
-// src/screen/list-components.ts
+// src/screen/list-components.js
 function MultiColumnListComponent({ items, ctx, selectedIndexRef }) {
   const [, forceUpdate] = (0, import_react2.useState)({});
   const termWidth = (process.stdout.columns || 80) - 8;
@@ -263,11 +261,13 @@ function MultiColumnListWithPreviewComponent({
     ...previewRows
   );
 }
-function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sortable = false, maxHeight, sortHighlightStyle, selectionMarker = " " }) {
+function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sortable = false, maxHeight, sortHighlightStyle, selectionMarker = " ", onSelectionChange }) {
   const [, forceUpdate] = (0, import_react2.useState)({});
   const [sortOrder, setSortOrder] = (0, import_react2.useState)("none");
   const [scrollOffset, setScrollOffset] = (0, import_react2.useState)(0);
   const scrollStateRef = (0, import_react2.useRef)({ scrollOffset: 0, maxHeight: 0, totalItems: 0 });
+  const itemsRef = (0, import_react2.useRef)(items);
+  itemsRef.current = items;
   const defaultGetTitle = (item) => {
     return getTitle ? getTitle(item) : typeof item.value === "string" ? item.value : item.value?.title || item.name;
   };
@@ -281,18 +281,24 @@ function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sor
       return titleA > titleB ? -1 : titleA < titleB ? 1 : 0;
     }
   }) : items;
+  const displayItemsRef = (0, import_react2.useRef)(displayItems);
+  displayItemsRef.current = displayItems;
   const effectiveMaxHeight = maxHeight || displayItems.length;
-  const canScroll = displayItems.length > effectiveMaxHeight;
+  const _canScroll = displayItems.length > effectiveMaxHeight;
   const maxScrollOffset = Math.max(0, displayItems.length - effectiveMaxHeight);
   const clampedScrollOffset = Math.min(Math.max(0, scrollOffset), maxScrollOffset);
   const visibleItems = displayItems.slice(clampedScrollOffset, clampedScrollOffset + effectiveMaxHeight);
   const canScrollUp = clampedScrollOffset > 0;
   const canScrollDown = clampedScrollOffset < maxScrollOffset;
   scrollStateRef.current = { scrollOffset, maxHeight: effectiveMaxHeight, totalItems: displayItems.length };
+  const onSelectionChangeRef = (0, import_react2.useRef)(onSelectionChange);
+  onSelectionChangeRef.current = onSelectionChange;
   (0, import_react2.useEffect)(() => {
     ctx.setAction("moveUp", () => {
       const newIndex = Math.max(0, selectedIndexRef.current - 1);
       selectedIndexRef.current = newIndex;
+      const list = displayItemsRef.current;
+      onSelectionChangeRef.current?.(newIndex, list[newIndex]);
       const { scrollOffset: currentScrollOffset, maxHeight: currentMaxHeight, totalItems } = scrollStateRef.current;
       const currentMaxScrollOffset = Math.max(0, totalItems - currentMaxHeight);
       const currentClampedScrollOffset = Math.min(Math.max(0, currentScrollOffset), currentMaxScrollOffset);
@@ -302,18 +308,11 @@ function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sor
       forceUpdate({});
     });
     ctx.setAction("moveDown", () => {
-      const currentItems = sortable && sortOrder !== "none" ? [...items].sort((a, b) => {
-        const titleA = titleGetter(a).toLowerCase();
-        const titleB = titleGetter(b).toLowerCase();
-        if (sortOrder === "asc") {
-          return titleA < titleB ? -1 : titleA > titleB ? 1 : 0;
-        } else {
-          return titleA > titleB ? -1 : titleA < titleB ? 1 : 0;
-        }
-      }) : items;
-      const maxIndex = currentItems.length - 1;
+      const currentItems = displayItemsRef.current;
+      const maxIndex = Math.max(0, currentItems.length - 1);
       const newIndex = Math.min(maxIndex, selectedIndexRef.current + 1);
       selectedIndexRef.current = newIndex;
+      onSelectionChangeRef.current?.(newIndex, currentItems[newIndex]);
       const { scrollOffset: currentScrollOffset, maxHeight: currentMaxHeight, totalItems } = scrollStateRef.current;
       const currentMaxScrollOffset = Math.max(0, totalItems - currentMaxHeight);
       const currentClampedScrollOffset = Math.min(Math.max(0, currentScrollOffset), currentMaxScrollOffset);
@@ -323,8 +322,7 @@ function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sor
       forceUpdate({});
     });
     ctx.setAction("scrollUp", () => {
-      const { scrollOffset: currentScrollOffset, maxHeight: currentMaxHeight, totalItems } = scrollStateRef.current;
-      const currentMaxScrollOffset = Math.max(0, totalItems - currentMaxHeight);
+      const { scrollOffset: currentScrollOffset } = scrollStateRef.current;
       const newScrollOffset = Math.max(0, currentScrollOffset - 1);
       setScrollOffset(newScrollOffset);
       forceUpdate({});
@@ -339,9 +337,9 @@ function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sor
     if (sortable) {
       ctx.setAction("toggleSort", () => {
         const nextSort = sortOrder === "none" ? "asc" : sortOrder === "asc" ? "desc" : "none";
-        const currentSelectedItem = displayItems[selectedIndexRef.current];
+        const currentSelectedItem = displayItemsRef.current[selectedIndexRef.current];
         setSortOrder(nextSort);
-        const newSortedItems = nextSort !== "none" ? [...items].sort((a, b) => {
+        const newSortedItems = nextSort !== "none" ? [...itemsRef.current].sort((a, b) => {
           const titleA = titleGetter(a).toLowerCase();
           const titleB = titleGetter(b).toLowerCase();
           if (nextSort === "asc") {
@@ -349,7 +347,7 @@ function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sor
           } else {
             return titleA > titleB ? -1 : titleA < titleB ? 1 : 0;
           }
-        }) : items;
+        }) : itemsRef.current;
         const newIndex = newSortedItems.findIndex((item) => item === currentSelectedItem);
         if (newIndex !== -1) {
           selectedIndexRef.current = newIndex;
@@ -487,8 +485,7 @@ function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sor
 }
 var import_react2, import_ink2, h2;
 var init_list_components = __esm({
-  "src/screen/list-components.ts"() {
-    "use strict";
+  "src/screen/list-components.js"() {
     import_react2 = __toESM(require("react"), 1);
     import_ink2 = require("ink");
     init_components();
@@ -496,7 +493,7 @@ var init_list_components = __esm({
   }
 });
 
-// src/screen/screens.ts
+// src/screen/screens.js
 function groupKeyBindings(bindings) {
   const groups = {};
   const enabledBindings = bindings.filter((b) => b.enabled !== false);
@@ -572,7 +569,7 @@ async function showScreen(config2) {
     let renderResult = null;
     let initialized = false;
     const Screen = () => {
-      const [updateCounter, setUpdateCounter] = (0, import_react3.useState)(0);
+      const [, setUpdateCounter] = (0, import_react3.useState)(0);
       if (!initialized) {
         const defaultBindings = [
           { key: "escape", caption: "go back", action: "back", protected: true, order: 1 },
@@ -691,7 +688,7 @@ async function showScreen(config2) {
           }
         }
         if (matchedBinding && actions[matchedBinding.action]) {
-          const actionResult = actions[matchedBinding.action]({
+          actions[matchedBinding.action]({
             input,
             key,
             binding: matchedBinding
@@ -821,8 +818,7 @@ async function showMultiColumnListWithPreviewScreen(config2) {
 }
 var import_react3, import_ink3, showMenuScreen, showWordGridScreen;
 var init_screens = __esm({
-  "src/screen/screens.ts"() {
-    "use strict";
+  "src/screen/screens.js"() {
     import_react3 = require("react");
     import_ink3 = require("ink");
     init_components();
@@ -832,7 +828,7 @@ var init_screens = __esm({
   }
 });
 
-// src/screen/ui-elements.ts
+// src/screen/ui-elements.js
 function ListItem({
   children,
   isSelected = false,
@@ -857,7 +853,7 @@ function TextBlock({
   color = "white",
   dimmed = false,
   bold = false,
-  maxWidth
+  maxWidth: _maxWidth
 }) {
   return (0, import_react4.createElement)(
     import_ink4.Box,
@@ -897,7 +893,7 @@ function GridCell({
     }, children)
   );
 }
-function InputField({ prompt, value, onChange, onSubmit }) {
+function InputField({ prompt, value, onChange: _onChange, onSubmit: _onSubmit }) {
   return (0, import_react4.createElement)(
     import_ink4.Box,
     { flexDirection: "column" },
@@ -911,33 +907,31 @@ function InputField({ prompt, value, onChange, onSubmit }) {
 }
 var import_react4, import_ink4;
 var init_ui_elements = __esm({
-  "src/screen/ui-elements.ts"() {
-    "use strict";
+  "src/screen/ui-elements.js"() {
     import_react4 = require("react");
     import_ink4 = require("ink");
   }
 });
 
-// src/screen/utils.ts
+// src/screen/utils.js
 function buildBreadcrumb(parts) {
   if (parts.length === 0) return "";
   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({
-  "src/screen/utils.ts"() {
-    "use strict";
+  "src/screen/utils.js"() {
   }
 });
 
-// src/screen/footer-builder.ts
+// src/screen/footer-builder.js
 function buildFooter(config2 = {}) {
   const {
     navigation = null,
@@ -988,8 +982,7 @@ function organizeFooterMessages(messages) {
 }
 var FooterPresets;
 var init_footer_builder = __esm({
-  "src/screen/footer-builder.ts"() {
-    "use strict";
+  "src/screen/footer-builder.js"() {
     FooterPresets = {
       /**
        * Menu screen footer
@@ -1048,7 +1041,7 @@ var init_footer_builder = __esm({
   }
 });
 
-// src/screen/index.ts
+// src/screen/index.js
 var screen_exports = {};
 __export(screen_exports, {
   Box: () => import_ink5.Box,
@@ -1074,6 +1067,7 @@ __export(screen_exports, {
   buildFooter: () => buildFooter,
   h: () => import_react5.createElement,
   load: () => load,
+  memo: () => import_react5.memo,
   organizeFooterMessages: () => organizeFooterMessages,
   showListScreen: () => showListScreen,
   showMenuScreen: () => showMenuScreen,
@@ -1084,6 +1078,7 @@ __export(screen_exports, {
   useCallback: () => import_react5.useCallback,
   useEffect: () => import_react5.useEffect,
   useInput: () => import_ink5.useInput,
+  useLayoutEffect: () => import_react5.useLayoutEffect,
   useMemo: () => import_react5.useMemo,
   useRef: () => import_react5.useRef,
   useState: () => import_react5.useState
@@ -1099,8 +1094,7 @@ async function load() {
 }
 var import_react5, import_ink5, loadPromise;
 var init_screen = __esm({
-  "src/screen/index.ts"() {
-    "use strict";
+  "src/screen/index.js"() {
     import_react5 = __toESM(require("react"), 1);
     import_ink5 = require("ink");
     init_screens();
@@ -1117,11 +1111,11 @@ var init_screen = __esm({
   }
 });
 
-// src/scripts/cli-runner.ts
-var import_node_path = __toESM(require("path"), 1);
+// src/scripts/cli-runner.js
+var import_node_path2 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 
-// src/args/index.ts
+// src/args/index.js
 var import_fs = require("fs");
 var import_path = require("path");
 var import_dotenv = require("dotenv");
@@ -1604,10 +1598,10 @@ var Args = class _Args {
   }
 };
 
-// src/params/index.ts
+// src/params/index.js
 var import_joi = __toESM(require("joi"), 1);
 
-// src/errors.ts
+// src/errors.js
 var FrameworkError = class extends Error {
   constructor(message) {
     super(message);
@@ -1633,7 +1627,7 @@ var FileDatabaseError = class extends FrameworkError {
   }
 };
 
-// src/params/custom-types.ts
+// src/params/custom-types.js
 var joiEdateType = (value, helpers) => {
   if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(value)) {
     const testDate = new Date(value);
@@ -1726,7 +1720,7 @@ function calculateTimeOffset(amount, unit, sign) {
   }
   return sign === "+" ? amount * multiplier : -amount * multiplier;
 }
-var joiStringArrayType = (type) => (value, helpers) => {
+var joiStringArrayType = (type) => (value, _helpers) => {
   if (value === void 0 || typeof value === "function") {
     return [];
   }
@@ -1752,7 +1746,7 @@ var joiStringArrayType = (type) => (value, helpers) => {
   return arr;
 };
 
-// src/params/index.ts
+// src/params/index.js
 var Params = class _Params {
   context;
   // Partial context during initialization
@@ -1944,7 +1938,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();
@@ -2012,7 +2006,7 @@ var Params = class _Params {
       definition = val;
       val = val.value;
     }
-    const def = this.assignDefinition(key, definition);
+    this.assignDefinition(key, definition);
     if (!this.runAllRegisteredSetters(key, val)) {
       this.params[key] = val;
     }
@@ -2020,6 +2014,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 +2052,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 +2078,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";
@@ -2116,11 +2125,11 @@ var Params = class _Params {
   }
 };
 
-// src/logger/index.ts
+// src/logger/index.js
 var import_chalk = __toESM(require("chalk"), 1);
 var import_util = __toESM(require("util"), 1);
 
-// src/logger/transports.ts
+// src/logger/transports.js
 var ConsoleTransport = class {
   write(payload) {
     console.info(payload);
@@ -2140,7 +2149,7 @@ var ParentProcessTransport = class {
   }
 };
 
-// src/logger/index.ts
+// src/logger/index.js
 var ALL_LEVELS = [
   "silly",
   "debug",
@@ -2213,6 +2222,7 @@ var Logger = class _Logger {
   }
   /**
    * Initialize logger from context and CLI parameters. Whatever is in options goes (after discovered params).
+   * Params are tracked under the `logger` module for --showUsedParams.
    */
   static init(context, options) {
     const paramDefs = {
@@ -2226,7 +2236,7 @@ var Logger = class _Logger {
       progressWithTimes: "boolean default false",
       progressThrottleMs: "number"
     };
-    const discovered = context.params.getAllForModule(paramDefs);
+    const discovered = context.params.getAllForModule("logger", paramDefs);
     const config2 = { ...discovered, ...options };
     const logger = new _Logger(context, config2);
     context.logger = logger;
@@ -2422,9 +2432,9 @@ var Logger = class _Logger {
   }
 };
 
-// src/init/index.ts
+// src/init/index.js
 var import_events = require("events");
-function extractComponentOptions(opts, componentName) {
+function extractComponentOptions(opts, _componentName) {
   const reservedKeys = ["overrides", "defaults", "modules"];
   const componentOptions = {};
   for (const [key, value] of Object.entries(opts)) {
@@ -2491,6 +2501,19 @@ function printAllParameters(context) {
 async function init(flow2, opts = {}) {
   let stop = false;
   let context = null;
+  let cleanupRan = false;
+  const runRegisteredCleanups = async (ctx) => {
+    if (cleanupRan) return;
+    cleanupRan = true;
+    const fns = [...ctx.cleanupFunctions].reverse();
+    for (const fn of fns) {
+      try {
+        await fn(ctx);
+      } catch (error) {
+        ctx.logger.warn("[cleanup] error in cleanup function:", error);
+      }
+    }
+  };
   try {
     try {
       const screenModule = await Promise.resolve().then(() => (init_screen(), screen_exports));
@@ -2513,13 +2536,24 @@ async function init(flow2, opts = {}) {
       printAllParameters(context);
       process.exit(0);
     }
+    let sigintCount = 0;
     process.on("SIGINT", async () => {
-      if (stop) {
-        context.logger.warn("[process] killed");
-        process.exit(2);
+      if (!context) return;
+      sigintCount += 1;
+      if (sigintCount === 1) {
+        stop = true;
+        context.logger.info(`>> emitting stop with allowance ${stopAllowance}`);
+        context.emitter.emit("stop", stopAllowance);
+        return;
       }
+      context.logger.warn("[process] second SIGINT: running cleanup then exit");
+      await runRegisteredCleanups(context);
+      process.exit(2);
+    });
+    process.on("SIGTERM", () => {
+      if (!context || stop) return;
       stop = true;
-      context.logger.info(`>> emitting stop with allowance ${stopAllowance}`);
+      context.logger.info(`>> SIGTERM: emitting stop with allowance ${stopAllowance}`);
       context.emitter.emit("stop", stopAllowance);
     });
     await flow2(context);
@@ -2544,33 +2578,62 @@ async function init(flow2, opts = {}) {
     }
   } finally {
     if (context) {
-      for (const fn of context.cleanupFunctions.reverse()) {
-        try {
-          await fn(context);
-        } catch (error) {
-          context.logger.warn("[cleanup] error in cleanup function:", error);
-        }
-      }
+      await runRegisteredCleanups(context);
     }
   }
 }
 
-// src/db/index.ts
+// src/db/index.js
 var import_knex = __toESM(require("knex"), 1);
+var KNEX_DEFAULTS = {
+  testConnection: true,
+  pool: { min: 2, max: 10 },
+  acquireConnectionTimeout: 1e4,
+  ssl: { rejectUnauthorized: false }
+};
 var Db = class {
-  knexInstance = null;
-  config;
-  logger;
-  queriesLog = [];
-  isConnected = false;
-  /**
-   * Constructor - accepts config object
-   * Use dbInit() function to initialize with Context
-   */
+  static async init(context, options = {}) {
+    const defs2 = {
+      dbName: "string",
+      dbConnectionString: "string",
+      dbProfile: "boolean default false"
+    };
+    const discovered = context?.params?.getAllForModule?.("db", defs2) ?? {};
+    const merged = { ...discovered, ...options };
+    let { dbName, dbConnectionString } = merged;
+    const { dbProfile } = merged;
+    if (!dbName && !dbConnectionString) {
+      dbName = "local";
+    }
+    if (dbName && /^(postgresql|mysql):\/\//.test(dbName)) {
+      dbConnectionString = dbName;
+      dbName = void 0;
+    }
+    if (dbName && !dbConnectionString) {
+      const paramName = `dbConnectionString${capitalizeFirstLetter(dbName)}`;
+      dbConnectionString = await context.params.get(paramName, "string");
+      if (!dbConnectionString) {
+        throw new ParamError(
+          `Db: cannot find dbConnectionString for dbName="${dbName}" (looked for param "${paramName}")`
+        );
+      }
+    }
+    const config2 = {
+      ...KNEX_DEFAULTS,
+      connectionString: dbConnectionString,
+      name: dbName || merged.name || "default",
+      profile: !!dbProfile,
+      logger: context.logger
+    };
+    return dbConnect(context, config2);
+  }
   constructor(config2) {
-    if (!config2.connectionString) {
+    if (!config2 || !config2.connectionString) {
       throw new ParamError("Db: connectionString is required");
     }
+    this.knexInstance = null;
+    this.isConnected = false;
+    this.queriesLog = [];
     this.config = {
       testConnection: true,
       profile: false,
@@ -2583,25 +2646,23 @@ var Db = class {
     };
     this.logger = this.config.logger;
     const instance = this;
-    const callableWrapper = function(...args) {
+    const callableWrapper = function() {
       throw new Error("This should never be called directly");
     };
     callableWrapper._instance = instance;
     return new Proxy(callableWrapper, {
-      // Intercept function calls: db('table')
-      apply: (target, thisArg, argumentsList) => {
+      apply: (target, _thisArg, argumentsList) => {
         const inst = target._instance;
         if (!inst.knexInstance) {
           throw new Error("Db: Not connected. Call connect() first.");
         }
         return inst.knexInstance(...argumentsList);
       },
-      // Intercept property access: db.schema, db.raw, etc.
       get: (target, prop) => {
         if (prop === "_instance") {
           return target._instance;
         }
-        const instance2 = target._instance;
+        const inst = target._instance;
         const ownMethods = [
           "connect",
           "disconnect",
@@ -2614,26 +2675,26 @@ var Db = class {
           "detectClient",
           "attachProfiler"
         ];
-        if (prop in instance2) {
-          const value = instance2[prop];
+        if (prop in inst) {
+          const value = inst[prop];
           if (typeof value === "function" && ownMethods.includes(prop)) {
-            return value.bind(instance2);
+            return value.bind(inst);
           }
           if (typeof value !== "function") {
             return value;
           }
         }
-        if (instance2.knexInstance) {
-          const knexProp = instance2.knexInstance[prop];
+        if (inst.knexInstance) {
+          const knexProp = inst.knexInstance[prop];
           if (typeof knexProp === "function") {
-            return knexProp.bind(instance2.knexInstance);
+            return knexProp.bind(inst.knexInstance);
           }
           return knexProp;
         }
-        if (prop in instance2) {
-          const method = instance2[prop];
+        if (prop in inst) {
+          const method = inst[prop];
           if (typeof method === "function") {
-            return method.bind(instance2);
+            return method.bind(inst);
           }
           return method;
         }
@@ -2641,9 +2702,6 @@ var Db = class {
       }
     });
   }
-  /**
-   * Detect database client type from connection string
-   */
   detectClient(connectionString) {
     if (connectionString.match(/^postgresql/)) {
       return "pg";
@@ -2653,9 +2711,6 @@ var Db = class {
     }
     return null;
   }
-  /**
-   * Connect to the database
-   */
   async connect() {
     if (this.isConnected && this.knexInstance) {
       this.logger.warn?.("[Db] Already connected");
@@ -2664,14 +2719,13 @@ var Db = class {
     const client = this.detectClient(this.config.connectionString);
     if (!client) {
       throw new ParamError(
-        `Db: Cannot determine client type from connection string. Expected postgresql:// or mysql://`
+        "Db: Cannot determine client type from connection string. Expected postgresql:// or mysql://"
       );
     }
     try {
       const connectionConfig = {
         connectionString: this.config.connectionString,
         family: 4
-        // Force IPv4 only (disable IPv6)
       };
       this.knexInstance = (0, import_knex.default)({
         client,
@@ -2687,7 +2741,9 @@ var Db = class {
         await this.testConnection();
       }
       this.isConnected = true;
-      this.logger.debug?.(`[Db] Connected to database "${this.config.name || this.config.connectionString}"`);
+      this.logger.debug?.(
+        `[Db] Connected to database "${this.config.name || this.config.connectionString}"`
+      );
     } catch (error) {
       if (error instanceof ParamError) {
         throw error;
@@ -2696,9 +2752,6 @@ var Db = class {
       throw new ParamError(`Db: Connection failed - ${errorMsg}`);
     }
   }
-  /**
-   * Disconnect from the database
-   */
   async disconnect() {
     if (!this.knexInstance) {
       return;
@@ -2708,16 +2761,15 @@ var Db = class {
       this.knexInstance = null;
       this.isConnected = false;
       this.queriesLog = [];
-      this.logger.debug?.(`[Db] Disconnected from database "${this.config.name || this.config.connectionString}"`);
+      this.logger.debug?.(
+        `[Db] Disconnected from database "${this.config.name || this.config.connectionString}"`
+      );
     } catch (error) {
       const errorMsg = this.getErrorMessage(error);
       this.logger.error?.(`[Db] Error disconnecting: ${errorMsg}`);
       throw error;
     }
   }
-  /**
-   * Extract error message from various error types
-   */
   getErrorMessage(error) {
     if (error instanceof AggregateError) {
       const errors = error.errors || [];
@@ -2742,9 +2794,11 @@ var Db = class {
             return `${code} (tried: ${addresses.join(", ")})`;
           }
         }
-        const uniqueMessages = [...new Set(errors.map((e) => {
-          return e instanceof Error ? e.message : String(e);
-        }))];
+        const uniqueMessages = [
+          ...new Set(
+            errors.map((e) => e instanceof Error ? e.message : String(e))
+          )
+        ];
         if (uniqueMessages.length === 1) {
           return uniqueMessages[0];
         }
@@ -2753,28 +2807,25 @@ var Db = class {
       return error.message || "Multiple errors occurred";
     }
     if (error instanceof Error) {
-      const errorWithCode = error;
-      if (errorWithCode.code) {
-        return `${errorWithCode.code}: ${error.message || String(error)}`;
+      const code = error.code;
+      if (code) {
+        return `${code}: ${error.message || String(error)}`;
       }
       return error.message || String(error);
     }
     if (typeof error === "string") {
       return error;
     }
-    if (error?.message) {
+    if (error && typeof error === "object" && "message" in error) {
       const msg = String(error.message);
-      const errorWithCode = error;
-      if (errorWithCode.code) {
-        return `${errorWithCode.code}: ${msg}`;
+      const code = error.code;
+      if (code) {
+        return `${code}: ${msg}`;
       }
       return msg;
     }
     return String(error) || "Unknown error";
   }
-  /**
-   * Test database connection
-   */
   async testConnection() {
     if (!this.knexInstance) {
       throw new Error("Db: Not connected. Call connect() first.");
@@ -2790,9 +2841,6 @@ var Db = class {
       throw new ParamError(`Db: Connection test failed - ${errorMsg}`);
     }
   }
-  /**
-   * Attach query profiler to log all queries
-   */
   attachProfiler() {
     if (!this.knexInstance) {
       return;
@@ -2802,7 +2850,7 @@ var Db = class {
     this.knexInstance.on("query", (query) => {
       query.__startTime = process.hrtime();
     });
-    this.knexInstance.on("query-response", (response, query) => {
+    this.knexInstance.on("query-response", (_response, query) => {
       const [seconds, nanoseconds] = process.hrtime(query.__startTime);
       const executionTimeMs = (seconds * 1e3 + nanoseconds / 1e6).toFixed(2);
       const logEntry = {
@@ -2817,15 +2865,9 @@ var Db = class {
       this.logger.error?.(`[Db] Query failed: ${query.sql}`, error);
     });
   }
-  /**
-   * Get query log (only available if profiling is enabled)
-   */
   getQueryLog() {
     return [...this.queriesLog];
   }
-  /**
-   * Check if a table exists
-   */
   async tableExists(tableName) {
     if (!this.knexInstance) {
       throw new Error("Db: Not connected. Call connect() first.");
@@ -2837,65 +2879,28 @@ var Db = class {
       throw error;
     }
   }
-  /**
-   * Get the underlying Knex instance (for advanced usage)
-   */
   getKnex() {
     if (!this.knexInstance) {
       throw new Error("Db: Not connected. Call connect() first.");
     }
     return this.knexInstance;
   }
-  /**
-   * Get connection status
-   */
   isConnectedToDb() {
     return this.isConnected && this.knexInstance !== null;
   }
-  /**
-   * Initialize Db with context (connects and registers disconnect cleanup).
-   * Params are read via getAllForModule("db", defs). Same as dbInit(context, dbNameOrConnectionString).
-   */
-  static async init(context, dbNameOrConnectionString) {
-    return dbFindAndConnect(context, dbNameOrConnectionString);
-  }
 };
 function capitalizeFirstLetter(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
-async function dbConnect(context, connectionString, name, dbProfile) {
-  const defs2 = {
-    testDbConnection: "boolean default true",
-    name: "string",
-    poolMin: "number default 2",
-    poolMax: "number default 10",
-    acquireConnectionTimeout: "number default 10000",
-    sslRejectUnauthorized: "boolean default false"
-  };
-  const paramsConfig = context.params.getAllForModule(defs2);
-  const config2 = {
-    connectionString,
-    name: paramsConfig.name || name || "default",
-    testConnection: paramsConfig.testDbConnection,
-    profile: dbProfile ?? false,
-    pool: {
-      min: paramsConfig.poolMin,
-      max: paramsConfig.poolMax
-    },
-    acquireConnectionTimeout: paramsConfig.acquireConnectionTimeout,
-    ssl: {
-      rejectUnauthorized: paramsConfig.sslRejectUnauthorized
-    },
-    logger: context.logger
-  };
+async function dbConnect(context, config2) {
   try {
     const db = new Db(config2);
     context.registerCleanup(async () => {
       await db.disconnect();
-      context.logger.debug(`[Db] instance "${name || connectionString}" destroyed`);
+      context.logger.debug?.(`[Db] instance "${config2.name}" disconnected`);
     });
     await db.connect();
-    context.logger.debug(`[Db] instance "${name || connectionString}" initialized`);
+    context.logger.debug?.(`[Db] instance "${config2.name}" initialized`);
     return db;
   } catch (error) {
     if (error instanceof ParamError) {
@@ -2905,48 +2910,11 @@ async function dbConnect(context, connectionString, name, dbProfile) {
     throw new ParamError(`[Db] connect error: ${errorMsg}`);
   }
 }
-async function dbFindAndConnect(context, dbNameOrConnectionString) {
-  let dbName;
-  let dbConnectionString;
-  let dbProfile;
-  if (dbNameOrConnectionString) {
-    if (dbNameOrConnectionString.match(/^(postgresql|mysql):\/\/[^\s]+:[^\s]+@[^\s]+:\d+\/[^\s]+$/)) {
-      dbName = void 0;
-      dbConnectionString = dbNameOrConnectionString;
-    } else {
-      dbName = dbNameOrConnectionString;
-    }
-  } else {
-    const defs2 = {
-      dbName: "string",
-      dbConnectionString: "string",
-      dbProfile: "boolean default false"
-    };
-    const paramsConfig = context.params.getAllForModule(defs2);
-    dbName = paramsConfig.dbName;
-    dbConnectionString = paramsConfig.dbConnectionString;
-    dbProfile = paramsConfig.dbProfile;
-  }
-  if (!dbName && !dbConnectionString) {
-    throw new ParamError("Db: either dbName or dbConnectionString must be specified");
-  }
-  if (dbName) {
-    const paramName = `dbConnectionString${capitalizeFirstLetter(dbName)}`;
-    dbConnectionString = await context.params.get(paramName, "string");
-    if (!dbConnectionString) {
-      throw new ParamError(
-        `Db: cannot find dbConnectionString for dbName="${dbName}" (looked for param "${paramName}")`
-      );
-    }
-  }
-  const db = await dbConnect(context, dbConnectionString, dbName, dbProfile);
-  return db;
-}
-async function dbInit(context, dbNameOrConnectionString) {
-  return await dbFindAndConnect(context, dbNameOrConnectionString);
-}
 
-// src/utils/date-utils.ts
+// src/tasks/index.js
+var import_node_os3 = __toESM(require("os"), 1);
+
+// 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)) {
@@ -2956,7 +2924,7 @@ function isTimestampFolder(folderName) {
   return !isNaN(date.getTime()) && date.getTime() > 0;
 }
 
-// src/utils/fs-utils.ts
+// src/utils/fs-utils.js
 var import_fs2 = __toESM(require("fs"), 1);
 var import_path2 = __toESM(require("path"), 1);
 async function ensurePath(...pathParts) {
@@ -2980,7 +2948,7 @@ function getFileExtension(dataType) {
   }
 }
 
-// src/utils/os-utils.ts
+// src/utils/os-utils.js
 var import_fs3 = __toESM(require("fs"), 1);
 var import_path3 = __toESM(require("path"), 1);
 var import_child_process = require("child_process");
@@ -3009,7 +2977,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;
@@ -3018,7 +2986,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((resolve2) => setTimeout(resolve2, ms));
 }
@@ -3027,8 +2995,82 @@ function toJsonColumn(value) {
   return JSON.stringify(value);
 }
 
-// src/tasks/taskUtils.ts
+// src/tasks/servicesRegistry.js
+var import_node_os = __toESM(require("os"), 1);
+
+// src/tasks/taskUtils.js
 var import_node_crypto = require("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) {
@@ -3036,89 +3078,84 @@ 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`);
     });
   }
 }
@@ -3129,11 +3166,226 @@ 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;
+}
+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 = import_node_os.default.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 = import_node_os.default.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 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}`);
+}
+
+// src/tasks/taskLogs.js
+var import_node_path = __toESM(require("path"), 1);
+
+// src/filedatabase/index.js
 var import_fs4 = __toESM(require("fs"), 1);
 var import_path4 = __toESM(require("path"), 1);
 
-// src/filedatabase/serializers.ts
+// src/filedatabase/serializers.js
 function detectDataType(data) {
   if (Array.isArray(data)) {
     return "json-array";
@@ -3165,7 +3417,7 @@ function deserializeData(rawData, dataType) {
   }
 }
 
-// src/filedatabase/index.ts
+// src/filedatabase/index.js
 var FileDatabase = class _FileDatabase {
   basePath;
   namespace;
@@ -3251,7 +3503,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("/"));
     }
@@ -3744,14 +3996,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);
@@ -3861,7 +4116,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) {
@@ -4155,7 +4410,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;
@@ -4208,6 +4463,89 @@ 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 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") {
@@ -4227,14 +4565,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);
@@ -4252,83 +4602,280 @@ function appendTaskIpcLog(context, task, payload) {
   });
 }
 
-// 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);
-    }
-    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());
-}
-
-// 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) {
   }
+  /**
+   * 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");
+  }
+  /**
+   * 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 };
+  }
+  /**
+   * 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 defs2 = {
+      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", defs2);
+    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, defs2, overrides = {}) {
+    const fullDefs = { ...defs2, 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.ts
-var TaskPing = class extends TaskMaster {
+// 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.ts
-var TaskSampleProcess = class extends TaskMaster {
-  stopRequested = false;
-  stopAllowanceMs = 0;
-  stopDecisionLogged = false;
+// 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;
@@ -4336,6 +4883,14 @@ var TaskSampleProcess = class extends TaskMaster {
       `[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;
@@ -4417,7 +4972,7 @@ var TaskSampleProcess = class extends TaskMaster {
   }
 };
 
-// src/tasks/coreTasks/TaskShellCommand.ts
+// src/tasks/coreTasks/TaskShellCommand.js
 var import_node_child_process = require("child_process");
 function runShellCommand(command, cwd) {
   return new Promise((resolve2, reject) => {
@@ -4447,7 +5002,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;
@@ -4496,8 +5071,8 @@ var TaskShellCommand = class extends TaskMaster {
   }
 };
 
-// src/tasks/coreTasks/TaskSystemInfo.ts
-var import_node_os = __toESM(require("os"), 1);
+// src/tasks/coreTasks/TaskSystemInfo.js
+var import_node_os2 = __toESM(require("os"), 1);
 var import_promises = __toESM(require("fs/promises"), 1);
 function toGb(valueBytes) {
   return `${(valueBytes / 1024 ** 3).toFixed(2)} GB`;
@@ -4516,13 +5091,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 = 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 +5132,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})`);
@@ -4568,8 +5152,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;
@@ -4600,8 +5207,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})`);
@@ -4616,45 +5261,203 @@ 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
+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;
+}
+
+// src/tasks/taskScriptRunner.js
 var import_node_child_process2 = require("child_process");
 
-// 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.");
@@ -4666,15 +5469,6 @@ 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 signalRunningTasksStop(context, runningTaskInstances, allowanceMs) {
   context.logger.warn?.(`[tasks] signaling ${runningTaskInstances.size} running task(s) to stop`);
   for (const [, taskInstance] of runningTaskInstances) {
@@ -4689,19 +5483,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,
@@ -4709,7 +5505,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 {
@@ -4736,13 +5533,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");
@@ -4757,19 +5557,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({
@@ -4777,7 +5590,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
       });
@@ -4789,195 +5603,361 @@ 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: import_node_os3.default.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,
+          target,
+          registry,
+          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,
-          historyTable,
-          claimedStopTask,
+          target,
           registry,
-          runningTaskInstances
-        ).then(async (outcome) => {
+          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;
     }
   }
 }
 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 defs2 = {
       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(defs2);
+    const discovered = context.params.getAllForModule("tasks", defs2);
     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
     });
   }
 };
 
-// src/scripts/cli-runner.ts
+// src/scripts/cli-runner.js
 var defs = {
-  dbName: "string default local",
   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`);
@@ -4985,11 +5965,8 @@ async function loadTasksModule(modulePath) {
   return imported.tasksRegistry;
 }
 var flow = async (context) => {
-  const {
-    dbName,
-    tasksModule
-  } = context.params.getAll(defs);
-  const db = await dbInit(context, dbName);
+  const { tasksModule } = context.params.getAll(defs);
+  const db = await Db.init(context);
   context.db = db;
   const registry = new TasksRegistry().addMany(defaultTasksRegistry.toObject());
   if (tasksModule) {