@nmakarov/cli-toolkit 0.18.0 → 0.23.0

package/dist/index.cjs

@@ -1,12 +1,3 @@
-"use strict";
-
-var __esmCache = {};
-var __loadESMSync = function(moduleName) {
-  if (!__esmCache[moduleName]) {
-    throw new Error(`ESM module "${moduleName}" not loaded. Please call the load() function first: const toolkit = require("@nmakarov/cli-toolkit"); await toolkit.load();`);
-  }
-  return __esmCache[moduleName];
-};
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -38,7 +29,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), 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);
@@ -112,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;
@@ -271,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;
   };
@@ -289,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);
@@ -310,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);
@@ -331,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({});
@@ -347,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") {
@@ -357,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;
@@ -495,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();
@@ -504,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);
@@ -580,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 },
@@ -699,7 +688,7 @@ async function showScreen(config2) {
           }
         }
         if (matchedBinding && actions[matchedBinding.action]) {
-          const actionResult = actions[matchedBinding.action]({
+          actions[matchedBinding.action]({
             input,
             key,
             binding: matchedBinding
@@ -829,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();
@@ -840,7 +828,7 @@ var init_screens = __esm({
   }
 });
 
-// src/screen/ui-elements.ts
+// src/screen/ui-elements.js
 function ListItem({
   children,
   isSelected = false,
@@ -865,7 +853,7 @@ function TextBlock({
   color = "white",
   dimmed = false,
   bold = false,
-  maxWidth
+  maxWidth: _maxWidth
 }) {
   return (0, import_react4.createElement)(
     import_ink4.Box,
@@ -905,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" },
@@ -919,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(path4, suffix = "") {
-  if (path4.length <= 1) {
-    return suffix ? `\u2190  ${suffix}` : path4[0] || "";
+function buildDetailBreadcrumb(path5, suffix = "") {
+  if (path5.length <= 1) {
+    return suffix ? `\u2190  ${suffix}` : path5[0] || "";
   }
-  const breadcrumb = buildBreadcrumb(path4);
+  const breadcrumb = buildBreadcrumb(path5);
   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,
@@ -996,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
@@ -1056,7 +1041,7 @@ var init_footer_builder = __esm({
   }
 });
 
-// src/screen/index.ts
+// src/screen/index.js
 async function load() {
   if (loadPromise) return loadPromise;
 
@@ -1065,8 +1050,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();
@@ -1083,9 +1067,10 @@ var init_screen = __esm({
   }
 });
 
-// src/index.ts
+// src/index.js
 var src_exports = {};
 __export(src_exports, {
+  AbstractTask: () => AbstractTask,
   Args: () => Args,
   Box: () => import_ink5.Box,
   Db: () => Db,
@@ -1101,13 +1086,15 @@ __export(src_exports, {
   MultiColumnListWithPreviewComponent: () => MultiColumnListWithPreviewComponent,
   Params: () => Params,
   React: () => import_react5.default,
+  S3: () => S3,
+  SERVICE_TASK_NAMES: () => SERVICE_TASK_NAMES,
   ScreenBody: () => ScreenBody,
   ScreenContainer: () => ScreenContainer,
   ScreenDivider: () => ScreenDivider,
   ScreenFooter: () => ScreenFooter,
   ScreenRow: () => ScreenRow,
   ScreenTitle: () => ScreenTitle,
-  TaskMaster: () => TaskMaster,
+  TaskGetLogs: () => TaskGetLogs,
   TaskPing: () => TaskPing,
   TaskSampleProcess: () => TaskSampleProcess,
   TaskShellCommand: () => TaskShellCommand,
@@ -1122,24 +1109,38 @@ __export(src_exports, {
   buildBreadcrumb: () => buildBreadcrumb,
   buildDetailBreadcrumb: () => buildDetailBreadcrumb,
   buildFooter: () => buildFooter,
-  dbConnect: () => dbConnect,
-  dbFindAndConnect: () => dbFindAndConnect,
-  dbInit: () => dbInit,
+  convertPattern: () => convertPattern,
   defaultFileSynopsisFunction: () => defaultFileSynopsisFunction,
   defaultTasksRegistry: () => defaultTasksRegistry,
   defaultVersionSynopsisFunction: () => defaultVersionSynopsisFunction,
   enqueueStopTask: () => enqueueStopTask,
   enqueueTask: () => enqueueTask,
   ensureTaskTables: () => ensureTaskTables,
+  flushTaskIpcLogs: () => flushTaskIpcLogs,
   getArgsInstance: () => getArgsInstance,
   h: () => import_react5.createElement,
+  ipcFileLogsTableNameForSourceResource: () => ipcFileLogsTableNameForSourceResource,
   joiEdateType: () => joiEdateType,
   joiStringArrayType: () => joiStringArrayType,
+  listAliveRunnerHeartbeats: () => listServicesRegistry,
+  listServicesRegistry: () => listServicesRegistry,
   listSources: () => listSources,
   listTables: () => listTables,
   load: () => load,
+  matchesParsedPattern: () => matchesParsedPattern,
+  memo: () => import_react5.memo,
+  mergeAllowedTasksWithServiceTasks: () => mergeAllowedTasksWithServiceTasks,
+  nextTimeMatch: () => nextTimeMatch,
+  normalizeAllowedTasks: () => normalizeAllowedTasks,
   organizeFooterMessages: () => organizeFooterMessages,
   queueToTableNames: () => queueToTableNames,
+  readTaskIpcLogsSnapshot: () => readTaskIpcLogsSnapshot,
+  registerInServicesRegistry: () => registerInServicesRegistry,
+  registerRunnerHeartbeat: () => registerInServicesRegistry,
+  resolveAsterisks: () => resolveAsterisks,
+  resolveIpcFileLogsDir: () => resolveIpcFileLogsDir,
+  resolveRanges: () => resolveRanges,
+  resolveSteps: () => resolveSteps,
   runNodeTaskScript: () => runNodeTaskScript,
   runTasksLoop: () => runTasksLoop,
   setupContext: () => setupContext,
@@ -1149,10 +1150,18 @@ __export(src_exports, {
   showMultiColumnListWithPreviewScreen: () => showMultiColumnListWithPreviewScreen,
   showScreen: () => showScreen,
   showWordGridScreen: () => showWordGridScreen,
+  taskHistoryInsertFromQueueRow: () => taskHistoryInsertFromQueueRow,
+  timeMatcher: () => timeMatcher,
+  touchRunnerHeartbeat: () => touchServicesRegistry,
+  touchServicesRegistry: () => touchServicesRegistry,
+  unregisterRunnerHeartbeat: () => unregisterServicesRegistry,
+  unregisterServicesRegistry: () => unregisterServicesRegistry,
+  updateServicesRegistryMetadata: () => updateServicesRegistryMetadata,
   updateTaskProgress: () => updateTaskProgress,
   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,
@@ -1160,7 +1169,7 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/args/index.ts
+// src/args/index.js
 var import_fs = require("fs");
 var import_path = require("path");
 var import_dotenv = require("dotenv");
@@ -1647,10 +1656,10 @@ function getArgsInstance() {
   return instance;
 }
 
-// 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);
@@ -1670,7 +1679,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);
@@ -1763,7 +1772,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 [];
   }
@@ -1789,7 +1798,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
@@ -1981,7 +1990,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();
@@ -2049,7 +2058,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;
     }
@@ -2057,6 +2066,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(defs) {
     return this.getAllForModule("script", defs);
@@ -2093,6 +2104,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>/...
    */
@@ -2106,9 +2130,9 @@ var Params = class _Params {
       if (!parenMatch) continue;
       const parts = parenMatch[1].split(":");
       if (parts.length < 3) continue;
-      const path4 = parts.slice(0, -2).join(":").replace(/^file:\/\//, "");
-      if (!path4 || path4.includes(paramsIndexPath)) continue;
-      const srcMatch = path4.match(/[/\\]src[/\\]([^/\\]+)(?:[/\\]|$)/);
+      const path5 = parts.slice(0, -2).join(":").replace(/^file:\/\//, "");
+      if (!path5 || path5.includes(paramsIndexPath)) continue;
+      const srcMatch = path5.match(/[/\\]src[/\\]([^/\\]+)(?:[/\\]|$)/);
       if (srcMatch) return srcMatch[1];
     }
     return "script";
@@ -2153,14 +2177,14 @@ var Params = class _Params {
   }
 };
 
-// src/screen.ts
+// src/index.js
 init_screen();
 
-// src/filedatabase/index.ts
+// src/filedatabase/index.js
 var import_fs4 = __toESM(require("fs"), 1);
 var import_path4 = __toESM(require("path"), 1);
 
-// src/utils/os-utils.ts
+// src/utils/os-utils.js
 var import_fs2 = __toESM(require("fs"), 1);
 var import_path2 = __toESM(require("path"), 1);
 var import_child_process = require("child_process");
@@ -2189,7 +2213,7 @@ function getFreeDiskSpace(targetPath) {
   }
 }
 
-// src/utils/fs-utils.ts
+// src/utils/fs-utils.js
 var import_fs3 = __toESM(require("fs"), 1);
 var import_path3 = __toESM(require("path"), 1);
 async function ensurePath(...pathParts) {
@@ -2213,7 +2237,7 @@ function getFileExtension(dataType) {
   }
 }
 
-// src/utils/format-utils.ts
+// src/utils/format-utils.js
 function bytesToHumanReadable(bytes) {
   if (bytes === 0) return "0 B";
   const k = 1024;
@@ -2222,7 +2246,7 @@ function bytesToHumanReadable(bytes) {
   return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
 }
 
-// src/utils/date-utils.ts
+// 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)) {
@@ -2232,7 +2256,7 @@ function isTimestampFolder(folderName) {
   return !isNaN(date.getTime()) && date.getTime() > 0;
 }
 
-// src/filedatabase/serializers.ts
+// src/filedatabase/serializers.js
 function detectDataType(data) {
   if (Array.isArray(data)) {
     return "json-array";
@@ -2264,7 +2288,7 @@ function deserializeData(rawData, dataType) {
   }
 }
 
-// src/filedatabase/synopsis-functions.ts
+// src/filedatabase/synopsis-functions.js
 function defaultFileSynopsisFunction(fileEntry, data) {
   if (!Array.isArray(data) || data.length === 0) {
     return { ...fileEntry };
@@ -2332,7 +2356,7 @@ function defaultVersionSynopsisFunction(metadata) {
   return result;
 }
 
-// src/filedatabase/index.ts
+// src/filedatabase/index.js
 var FileDatabase = class _FileDatabase {
   basePath;
   namespace;
@@ -2418,7 +2442,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("/"));
     }
@@ -2911,14 +2935,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);
@@ -3028,7 +3055,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) {
@@ -3343,22 +3370,57 @@ function listSources(basePath) {
   }
 }
 
-// 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 defs = {
+      dbName: "string",
+      dbConnectionString: "string",
+      dbProfile: "boolean default false"
+    };
+    const discovered = context?.params?.getAllForModule?.("db", defs) ?? {};
+    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,
@@ -3371,25 +3433,23 @@ var Db = class {
     };
     this.logger = this.config.logger;
     const instance2 = this;
-    const callableWrapper = function(...args) {
+    const callableWrapper = function() {
       throw new Error("This should never be called directly");
     };
     callableWrapper._instance = instance2;
     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 instance3 = target._instance;
+        const inst = target._instance;
         const ownMethods = [
           "connect",
           "disconnect",
@@ -3402,26 +3462,26 @@ var Db = class {
           "detectClient",
           "attachProfiler"
         ];
-        if (prop in instance3) {
-          const value = instance3[prop];
+        if (prop in inst) {
+          const value = inst[prop];
           if (typeof value === "function" && ownMethods.includes(prop)) {
-            return value.bind(instance3);
+            return value.bind(inst);
           }
           if (typeof value !== "function") {
             return value;
           }
         }
-        if (instance3.knexInstance) {
-          const knexProp = instance3.knexInstance[prop];
+        if (inst.knexInstance) {
+          const knexProp = inst.knexInstance[prop];
           if (typeof knexProp === "function") {
-            return knexProp.bind(instance3.knexInstance);
+            return knexProp.bind(inst.knexInstance);
           }
           return knexProp;
         }
-        if (prop in instance3) {
-          const method = instance3[prop];
+        if (prop in inst) {
+          const method = inst[prop];
           if (typeof method === "function") {
-            return method.bind(instance3);
+            return method.bind(inst);
           }
           return method;
         }
@@ -3429,9 +3489,6 @@ var Db = class {
       }
     });
   }
-  /**
-   * Detect database client type from connection string
-   */
   detectClient(connectionString) {
     if (connectionString.match(/^postgresql/)) {
       return "pg";
@@ -3441,9 +3498,6 @@ var Db = class {
     }
     return null;
   }
-  /**
-   * Connect to the database
-   */
   async connect() {
     if (this.isConnected && this.knexInstance) {
       this.logger.warn?.("[Db] Already connected");
@@ -3452,14 +3506,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,
@@ -3475,7 +3528,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;
@@ -3484,9 +3539,6 @@ var Db = class {
       throw new ParamError(`Db: Connection failed - ${errorMsg}`);
     }
   }
-  /**
-   * Disconnect from the database
-   */
   async disconnect() {
     if (!this.knexInstance) {
       return;
@@ -3496,16 +3548,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 || [];
@@ -3530,9 +3581,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];
         }
@@ -3541,28 +3594,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.");
@@ -3578,9 +3628,6 @@ var Db = class {
       throw new ParamError(`Db: Connection test failed - ${errorMsg}`);
     }
   }
-  /**
-   * Attach query profiler to log all queries
-   */
   attachProfiler() {
     if (!this.knexInstance) {
       return;
@@ -3590,7 +3637,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 = {
@@ -3605,15 +3652,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.");
@@ -3625,65 +3666,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 defs = {
-    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(defs);
-  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) {
@@ -3693,52 +3697,255 @@ 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 defs = {
-      dbName: "string",
-      dbConnectionString: "string",
-      dbProfile: "boolean default false"
+
+// src/s3/index.js
+var import_client_s3 = require("@aws-sdk/client-s3");
+var DEFAULT_PROFILE = "local";
+function capitalize(str) {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+var S3 = class _S3 {
+  /**
+   * Build an S3 instance. Reads bucket profile from --bucket (default "local"),
+   * then resolves per-profile params, builds the SDK client, and returns the
+   * instance. Optionally pings the bucket once to verify reachability.
+   */
+  static async init(context, options = {}) {
+    const profileDef = { bucket: "string" };
+    const discovered = context?.params?.getAllForModule?.("s3", profileDef) ?? {};
+    const profile = options.bucket ?? discovered.bucket ?? DEFAULT_PROFILE;
+    const cap = capitalize(profile);
+    const config2 = {
+      profile,
+      bucketName: options.bucketName ?? await context.params.get(`s3Bucket${cap}`, "string"),
+      region: options.region ?? await context.params.get(`s3Region${cap}`, "string default us-east-1"),
+      endpoint: options.endpoint ?? await context.params.get(`s3Endpoint${cap}`, "string"),
+      forcePathStyle: options.forcePathStyle ?? await context.params.get(`s3ForcePathStyle${cap}`, "boolean default false"),
+      accessKeyId: options.accessKeyId ?? await context.params.get(`s3AccessKeyId${cap}`, "string"),
+      secretAccessKey: options.secretAccessKey ?? await context.params.get(`s3SecretAccessKey${cap}`, "string")
     };
-    const paramsConfig = context.params.getAllForModule(defs);
-    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) {
+    if (!config2.bucketName) {
       throw new ParamError(
-        `Db: cannot find dbConnectionString for dbName="${dbName}" (looked for param "${paramName}")`
+        `S3: bucket name not configured for profile "${profile}" (set s3Bucket${cap} or S3_BUCKET_${profile.toUpperCase()})`
       );
     }
+    const s3 = new _S3(context, config2);
+    if (options.testBucket !== false) {
+      try {
+        await s3.bucketExists();
+        context.logger?.debug?.(
+          `[S3] profile="${profile}" bucket="${config2.bucketName}" reachable`
+        );
+      } catch (err) {
+        context.logger?.warn?.(
+          `[S3] profile="${profile}" bucket="${config2.bucketName}" reachability test failed: ${err?.message ?? err}`
+        );
+      }
+    }
+    return s3;
+  }
+  constructor(context, config2) {
+    this.logger = context?.logger ?? console;
+    this.profile = config2.profile;
+    this.bucketName = config2.bucketName;
+    this.region = config2.region;
+    this.endpoint = config2.endpoint || null;
+    const clientConfig = { region: config2.region };
+    if (config2.endpoint) clientConfig.endpoint = config2.endpoint;
+    if (config2.forcePathStyle) clientConfig.forcePathStyle = true;
+    if (config2.accessKeyId && config2.secretAccessKey) {
+      clientConfig.credentials = {
+        accessKeyId: config2.accessKeyId,
+        secretAccessKey: config2.secretAccessKey
+      };
+    }
+    this.client = new import_client_s3.S3Client(clientConfig);
   }
-  const db = await dbConnect(context, dbConnectionString, dbName, dbProfile);
-  return db;
-}
-async function dbInit(context, dbNameOrConnectionString) {
-  return await dbFindAndConnect(context, dbNameOrConnectionString);
-}
+  // ── info ────────────────────────────────────────────────────────────────
+  getBucketName() {
+    return this.bucketName;
+  }
+  getProfile() {
+    return this.profile;
+  }
+  getRegion() {
+    return this.region;
+  }
+  getEndpoint() {
+    return this.endpoint;
+  }
+  // ── reachability ────────────────────────────────────────────────────────
+  async bucketExists() {
+    await this.client.send(new import_client_s3.HeadBucketCommand({ Bucket: this.bucketName }));
+    return true;
+  }
+  // ── HEAD / GET ──────────────────────────────────────────────────────────
+  /** Returns null on 404; never throws for "missing". Other errors throw. */
+  async headObject(key) {
+    try {
+      const out = await this.client.send(new import_client_s3.HeadObjectCommand({
+        Bucket: this.bucketName,
+        Key: key
+      }));
+      return {
+        etag: out.ETag,
+        size: out.ContentLength,
+        contentType: out.ContentType,
+        lastModified: out.LastModified,
+        metadata: out.Metadata,
+        storageClass: out.StorageClass
+      };
+    } catch (err) {
+      if (this._isNotFound(err)) return null;
+      throw err;
+    }
+  }
+  /** Returns { body: Readable, contentType, contentLength, etag, ... } or null on 404. */
+  async getObject(key) {
+    try {
+      const out = await this.client.send(new import_client_s3.GetObjectCommand({
+        Bucket: this.bucketName,
+        Key: key
+      }));
+      return {
+        body: out.Body,
+        contentType: out.ContentType,
+        contentLength: out.ContentLength,
+        etag: out.ETag,
+        lastModified: out.LastModified,
+        metadata: out.Metadata
+      };
+    } catch (err) {
+      if (this._isNotFound(err)) return null;
+      throw err;
+    }
+  }
+  /** Buffers the whole object. Use only for small objects (manifests, JSON). */
+  async getObjectBytes(key) {
+    const obj = await this.getObject(key);
+    if (!obj) return null;
+    const chunks = [];
+    for await (const chunk of obj.body) chunks.push(chunk);
+    return { ...obj, body: Buffer.concat(chunks) };
+  }
+  /** Convenience for JSON manifests. Returns parsed object or null on 404. */
+  async getJson(key) {
+    const obj = await this.getObjectBytes(key);
+    if (!obj) return null;
+    return JSON.parse(obj.body.toString("utf8"));
+  }
+  // ── PUT ─────────────────────────────────────────────────────────────────
+  async putObject({ key, body, contentType, contentLength, tags, metadata }) {
+    const cmd = new import_client_s3.PutObjectCommand({
+      Bucket: this.bucketName,
+      Key: key,
+      Body: body,
+      ...contentType && { ContentType: contentType },
+      ...contentLength != null && { ContentLength: contentLength },
+      ...metadata && { Metadata: metadata },
+      ...tags && { Tagging: this._tagsToQuery(tags) }
+    });
+    return this.client.send(cmd);
+  }
+  /** Convenience for JSON manifests. */
+  async putJson(key, value, opts = {}) {
+    const json = JSON.stringify(value, null, opts.pretty ? 2 : 0);
+    const body = Buffer.from(json, "utf8");
+    return this.putObject({
+      key,
+      body,
+      contentType: "application/json",
+      contentLength: body.length,
+      tags: opts.tags,
+      metadata: opts.metadata
+    });
+  }
+  // ── DELETE ──────────────────────────────────────────────────────────────
+  async deleteObject(key) {
+    return this.client.send(new import_client_s3.DeleteObjectCommand({
+      Bucket: this.bucketName,
+      Key: key
+    }));
+  }
+  // ── COPY (for migration: legacy → new bucket, or intra-bucket "rename") ─
+  async copyObject({ sourceBucket, sourceKey, key, contentType, metadata, tags }) {
+    const src = sourceBucket || this.bucketName;
+    const cmd = new import_client_s3.CopyObjectCommand({
+      Bucket: this.bucketName,
+      Key: key,
+      CopySource: encodeURIComponent(`${src}/${sourceKey}`),
+      ...contentType && {
+        ContentType: contentType,
+        MetadataDirective: "REPLACE"
+      },
+      ...metadata && {
+        Metadata: metadata,
+        MetadataDirective: "REPLACE"
+      },
+      ...tags && {
+        Tagging: this._tagsToQuery(tags),
+        TaggingDirective: "REPLACE"
+      }
+    });
+    return this.client.send(cmd);
+  }
+  // ── LIST ────────────────────────────────────────────────────────────────
+  async listObjects(prefix, { keysOnly = false, maxKeys = 1e3, continuationToken } = {}) {
+    const out = await this.client.send(new import_client_s3.ListObjectsV2Command({
+      Bucket: this.bucketName,
+      Prefix: prefix,
+      MaxKeys: maxKeys,
+      ContinuationToken: continuationToken
+    }));
+    const items = (out.Contents ?? []).map((o) => ({
+      key: o.Key,
+      size: o.Size,
+      etag: o.ETag,
+      lastModified: o.LastModified,
+      storageClass: o.StorageClass
+    }));
+    return {
+      items: keysOnly ? items.map((i) => i.key) : items,
+      isTruncated: !!out.IsTruncated,
+      nextContinuationToken: out.NextContinuationToken
+    };
+  }
+  // ── TAGS (used for lifecycle rules, e.g. status=closed → Glacier IR) ────
+  async putObjectTagging(key, tags) {
+    return this.client.send(new import_client_s3.PutObjectTaggingCommand({
+      Bucket: this.bucketName,
+      Key: key,
+      Tagging: { TagSet: this._tagsToTagSet(tags) }
+    }));
+  }
+  async getObjectTagging(key) {
+    const out = await this.client.send(new import_client_s3.GetObjectTaggingCommand({
+      Bucket: this.bucketName,
+      Key: key
+    }));
+    const tags = {};
+    for (const t of out.TagSet ?? []) tags[t.Key] = t.Value;
+    return tags;
+  }
+  // ── internals ───────────────────────────────────────────────────────────
+  _isNotFound(err) {
+    const status = err?.$metadata?.httpStatusCode;
+    return status === 404 || err?.name === "NotFound" || err?.name === "NoSuchKey" || err?.Code === "NoSuchKey";
+  }
+  _tagsToQuery(tags) {
+    return Object.entries(tags).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&");
+  }
+  _tagsToTagSet(tags) {
+    return Object.entries(tags).map(([Key, Value]) => ({ Key, Value: String(Value) }));
+  }
+};
 
-// 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);
@@ -3758,7 +3965,7 @@ var ParentProcessTransport = class {
   }
 };
 
-// src/logger/index.ts
+// src/logger/index.js
 var ALL_LEVELS = [
   "silly",
   "debug",
@@ -3831,6 +4038,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 = {
@@ -3844,7 +4052,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;
@@ -4040,9 +4248,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)) {
@@ -4087,7 +4295,10 @@ function setupContext(opts = {}) {
   return setup(opts);
 }
 
-// src/utils/core-utils.ts
+// src/tasks/index.js
+var import_node_os3 = __toESM(require("os"), 1);
+
+// src/utils/core-utils.js
 function sleepMs(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
@@ -4096,8 +4307,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) {
@@ -4105,105 +4390,117 @@ function getDb(context) {
   }
   return db;
 }
-function queueToTableNames(queue) {
-  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(queue)) {
-    throw new Error(`Invalid queue name "${queue}". Use letters, numbers, underscore only.`);
-  }
+function queueToTableNames(queueName) {
+  return {
+    tasksTable: queueName,
+    historyTable: `${queueName}_history`,
+    registryTable: `${queueName}_services_registry`
+  };
+}
+function defineTasksTable(t, db, tableNameForIndex) {
+  t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
+  t.timestamp("created_at").notNullable().defaultTo(db.fn.now());
+  t.timestamp("started_at");
+  t.timestamp("completed_at");
+  t.integer("priority").notNullable().defaultTo(50);
+  t.text("schedule");
+  t.timestamp("next_run_at").defaultTo(null);
+  t.timestamp("past_due").defaultTo(null);
+  t.text("name").notNullable();
+  t.text("opid");
+  t.json("params");
+  t.text("service_group");
+  t.integer("instance_number");
+  t.text("service_name");
+  t.text("server_name");
+  t.text("status").notNullable().defaultTo("idle");
+  t.timestamp("status_changed_at").defaultTo(null);
+  t.text("progress");
+  t.boolean("success");
+  t.json("results");
+  t.index(["service_group", "status", "priority", "created_at"], `${tableNameForIndex}_claim_idx`);
+  t.index(["service_group", "name"], `${tableNameForIndex}_group_name_idx`);
+}
+function taskHistoryInsertFromQueueRow(row, overrides) {
+  const { id, ...snapshot } = row;
+  void id;
   return {
-    tasksTable: queue,
-    historyTable: `${queue}_history`
+    ...snapshot,
+    ...overrides
   };
 }
 async function ensureTaskTables(context, options = {}) {
-  const queue = options.queue ?? "tasks";
+  const queueName = options.queueName ?? "tasks";
   const recreate = options.recreate ?? false;
   const db = getDb(context);
-  const { tasksTable, historyTable } = queueToTableNames(queue);
+  const { tasksTable, historyTable, registryTable } = queueToTableNames(queueName);
   const needsTasks = recreate ? true : !await db.tableExists(tasksTable);
   const needsHistory = recreate ? true : !await db.tableExists(historyTable);
+  const needsRegistry = recreate ? true : !await db.tableExists(registryTable);
   if (recreate) {
     await db.schema.dropTableIfExists(historyTable);
     await db.schema.dropTableIfExists(tasksTable);
+    await db.schema.dropTableIfExists(registryTable);
   }
   if (needsTasks) {
     await db.raw(`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`);
     await db.schema.createTable(tasksTable, (t) => {
-      t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
-      t.timestamp("created_at").notNullable().defaultTo(db.fn.now());
-      t.timestamp("started_at");
-      t.timestamp("completed_at");
-      t.integer("priority").notNullable().defaultTo(0);
-      t.text("schedule");
-      t.timestamp("past_due").defaultTo(null);
-      t.text("target").notNullable();
-      t.text("task").notNullable();
-      t.json("params");
-      t.text("opid");
-      t.timestamp("paused_at").defaultTo(null);
-      t.text("progress");
-      t.boolean("success");
-      t.json("results");
-    });
-    await db.schema.alterTable(tasksTable, (t) => {
-      t.index(["target", "started_at", "created_at"], `${tasksTable}_target_started_created_idx`);
-      t.index(["target", "past_due", "priority", "created_at"], `${tasksTable}_target_past_due_priority_created_idx`);
-      t.index(["target", "task"], `${tasksTable}_target_task_idx`);
-    });
-  }
-  const tasksHasOpid = await db.schema.hasColumn(tasksTable, "opid");
-  if (!tasksHasOpid) {
-    await db.schema.alterTable(tasksTable, (t) => {
-      t.text("opid");
-    });
-  }
-  const tasksHasPausedAt = await db.schema.hasColumn(tasksTable, "paused_at");
-  if (!tasksHasPausedAt) {
-    await db.schema.alterTable(tasksTable, (t) => {
-      t.timestamp("paused_at").defaultTo(null);
+      defineTasksTable(t, db, tasksTable);
     });
   }
   if (needsHistory) {
     await db.schema.createTable(historyTable, (t) => {
-      t.uuid("id").notNullable();
-      t.timestamp("created_at").notNullable();
-      t.timestamp("started_at");
-      t.timestamp("completed_at");
-      t.integer("priority").notNullable().defaultTo(0);
-      t.text("schedule");
-      t.timestamp("past_due").defaultTo(null);
-      t.text("target").notNullable();
-      t.text("task").notNullable();
-      t.json("params");
-      t.text("opid");
-      t.text("progress");
-      t.boolean("success");
-      t.json("results");
-    });
-    await db.schema.alterTable(historyTable, (t) => {
-      t.index(["target", "created_at"], `${historyTable}_target_created_idx`);
-      t.index(["task", "created_at"], `${historyTable}_task_created_idx`);
+      defineTasksTable(t, db, historyTable);
     });
   }
-  const historyHasOpid = await db.schema.hasColumn(historyTable, "opid");
-  if (!historyHasOpid) {
-    await db.schema.alterTable(historyTable, (t) => {
-      t.text("opid");
+  if (needsRegistry) {
+    await db.schema.createTable(registryTable, (t) => {
+      t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
+      t.text("queue_name").notNullable();
+      t.text("service_group").notNullable();
+      t.integer("instance_number").notNullable().defaultTo(1);
+      t.text("service_name").notNullable();
+      t.text("server_name").notNullable();
+      t.integer("pid");
+      t.json("metadata");
+      t.timestamp("created_at").notNullable().defaultTo(db.fn.now());
+      t.timestamp("last_seen_at").notNullable().defaultTo(db.fn.now());
+      t.unique(["queue_name", "service_name"], `${registryTable}_queue_name_service_name_uniq`);
+      t.index(["queue_name", "service_group", "last_seen_at"], `${registryTable}_queue_group_seen_idx`);
+      t.index(["queue_name", "last_seen_at"], `${registryTable}_queue_seen_idx`);
     });
   }
 }
 async function enqueueTask(context, options) {
   const db = getDb(context);
-  const queue = options.queue ?? "tasks";
-  const { tasksTable } = queueToTableNames(queue);
+  const queueName = options.queueName ?? "tasks";
+  const { tasksTable } = queueToTableNames(queueName);
   const id = (0, import_node_crypto.randomUUID)();
+  const name = options.name ?? options.task;
+  if (!name) {
+    throw new Error("enqueueTask: name (or task) is required");
+  }
+  const schedule = options.schedule?.trim() ? options.schedule : null;
+  let nextRunAt = null;
+  if (options.nextRunAt !== void 0) {
+    nextRunAt = options.nextRunAt == null ? null : new Date(options.nextRunAt);
+  } else if (schedule) {
+    nextRunAt = nextTimeMatch(schedule, /* @__PURE__ */ new Date());
+  }
   await db(tasksTable).insert({
     id,
-    target: options.target,
-    task: options.task,
+    name,
     params: toJsonColumn(options.params ?? null),
     opid: options.opid ?? null,
-    priority: options.priority ?? 0,
-    schedule: options.schedule ?? null
+    priority: options.priority ?? 50,
+    schedule,
+    next_run_at: nextRunAt,
+    service_group: options.serviceGroup ?? null,
+    instance_number: options.instanceNumber ?? null,
+    service_name: options.serviceName ?? null,
+    server_name: options.serverName ?? null,
+    status: "idle",
+    status_changed_at: db.fn.now()
   });
   return id;
 }
@@ -4214,59 +4511,397 @@ async function updateTaskProgress(context, tasksTable, taskId, progress) {
   });
 }
 
-// src/tasks/taskLogs.ts
-function getLogsState(context) {
-  const holder = context;
-  if (holder.__tasksLogsState) return holder.__tasksLogsState;
-  const basePath = holder.params?.get?.("tasksLogsBasePath") || "./data";
-  const namespace = holder.params?.get?.("tasksLogsNamespace") || "tasks-logs";
-  const tableName = holder.params?.get?.("tasksLogsTable") || "runner";
-  const errorTableName = holder.params?.get?.("tasksErrorLogsTable") || `${tableName}-errors`;
-  const maxVersionsRaw = Number(holder.params?.get?.("tasksLogsMaxVersions"));
-  const pageSizeRaw = Number(holder.params?.get?.("tasksLogsPageSize"));
-  const errorDb = new FileDatabase({
-    basePath,
-    namespace,
-    tableName: errorTableName,
-    versioned: true,
-    useMetadata: true,
-    maxVersions: Number.isFinite(maxVersionsRaw) && maxVersionsRaw > 0 ? maxVersionsRaw : 20,
-    pageSize: Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 2e3,
-    logger: holder.logger
-  });
-  const enabledRaw = holder.params?.get?.("tasksLogsEnabled");
-  const enabled = enabledRaw === void 0 ? true : !!enabledRaw;
-  if (!enabled) {
-    const disabledState = {
-      db: null,
-      errorDb,
-      queue: Promise.resolve(),
-      initialized: true,
-      errorInitialized: false
-    };
-    holder.__tasksLogsState = disabledState;
-    return disabledState;
+// src/tasks/servicesRegistry.js
+function getDb2(context) {
+  const db = context.db;
+  if (!db) {
+    throw new Error("Services registry requires context.db");
   }
-  const db = new FileDatabase({
-    basePath,
-    namespace,
-    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,
-    queue: Promise.resolve(),
-    initialized: false,
+  return db;
+}
+function parseMetadataColumn(value) {
+  if (!value) return {};
+  if (typeof value === "object" && !Array.isArray(value)) return value;
+  if (typeof value === "string") {
+    try {
+      const p = JSON.parse(value);
+      return p && typeof p === "object" && !Array.isArray(value) ? p : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+var DEFAULT_GROUP_MAX_INSTANCES = {
+  intake: 1,
+  harvest: 1,
+  harvester: 0,
+  loader: 0,
+  photos: 0,
+  photosprocessor: 0,
+  ingest: 0
+};
+function sanitizeNamePart(raw) {
+  const s = String(raw || "").trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return s.slice(0, 80) || "runner";
+}
+function resolveMaxInstances(serviceGroup, override) {
+  if (override !== void 0 && Number.isFinite(override)) {
+    return Math.max(0, Math.floor(Number(override)));
+  }
+  const g = serviceGroup.trim().toLowerCase();
+  return DEFAULT_GROUP_MAX_INSTANCES[g] ?? 0;
+}
+async function countAliveInGroup(db, registryTable, queueName, serviceGroup, staleMs, excludeRowId) {
+  const cutoff = new Date(Date.now() - staleMs);
+  let q = db(registryTable).where({ queue_name: queueName, service_group: serviceGroup }).where("last_seen_at", ">", cutoff);
+  if (excludeRowId) {
+    q = q.whereNot("id", excludeRowId);
+  }
+  const row = await q.count("id as count").first();
+  return Number(row?.count ?? 0);
+}
+async function getOccupiedInstanceSlots(db, registryTable, queueName, serviceGroup, staleMs) {
+  const cutoff = new Date(Date.now() - staleMs);
+  const rows = await db(registryTable).where({ queue_name: queueName, service_group: serviceGroup }).where("last_seen_at", ">", cutoff).select("instance_number");
+  const set = /* @__PURE__ */ new Set();
+  for (const r of rows) {
+    const n = Number(r.instance_number);
+    if (Number.isFinite(n) && n >= 1) set.add(Math.floor(n));
+  }
+  return set;
+}
+function isUniqueViolation(error) {
+  const code = error?.code ?? error?.errno;
+  return code === "23505" || String(error?.message || "").includes("duplicate key");
+}
+function buildMetadata(options) {
+  const base = options.metadata && typeof options.metadata === "object" ? { ...options.metadata } : {};
+  if (options.target) {
+    base.runnerTarget = options.target;
+  }
+  return toJsonColumn(Object.keys(base).length ? base : null);
+}
+function allocateInstanceNumber(occupied, explicit, maxSlots) {
+  if (explicit !== void 0 && explicit !== null && Number.isFinite(Number(explicit))) {
+    const e = Math.max(1, Math.floor(Number(explicit)));
+    if (occupied.has(e)) {
+      throw new Error(`[services-registry] instance slot ${e} is already occupied by an alive peer`);
+    }
+    if (maxSlots !== void 0 && maxSlots > 0 && e > maxSlots) {
+      throw new Error(`[services-registry] instance ${e} exceeds configured max slots ${maxSlots} for this group`);
+    }
+    return e;
+  }
+  const cap = maxSlots !== void 0 && maxSlots > 0 ? maxSlots : 1e4;
+  for (let n = 1; n <= cap; n++) {
+    if (!occupied.has(n)) return n;
+  }
+  throw new Error(`[services-registry] no free instance slot (searched 1..${cap})`);
+}
+function defaultServiceName(groupBase, hostBase, instanceNumber) {
+  return `${groupBase}-${hostBase}-${instanceNumber}`;
+}
+async function registerInServicesRegistry(context, options) {
+  const db = getDb2(context);
+  const registryTable = queueToTableNames(options.queueName).registryTable;
+  const serviceGroup = options.serviceGroup.trim();
+  if (!serviceGroup) {
+    throw new Error("registerInServicesRegistry: serviceGroup is required");
+  }
+  const serverName = 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 updateServicesRegistryMetadata(context, registration, patch) {
+  const db = getDb2(context);
+  const row = await db(registration.registryTable).where({ id: registration.rowId }).first();
+  const prev = parseMetadataColumn(row?.metadata);
+  const merged = { ...prev, ...patch };
+  await db(registration.registryTable).where({ id: registration.rowId }).update({
+    metadata: toJsonColumn(merged),
+    last_seen_at: db.fn.now()
+  });
+  context.logger.info?.(`[services-registry] metadata updated for ${registration.serviceName}`);
+}
+async function unregisterServicesRegistry(context, registration) {
+  const db = getDb2(context);
+  await db(registration.registryTable).where({ id: registration.rowId }).delete();
+  context.logger.info?.(`[services-registry] unregistered name=${registration.serviceName} id=${registration.rowId}`);
+}
+async function listServicesRegistry(context, options = { queueName: "tasks" }) {
+  const db = getDb2(context);
+  const staleMs = options.staleMs ?? 6e4;
+  const cutoff = new Date(Date.now() - staleMs);
+  const table = queueToTableNames(options.queueName).registryTable;
+  let q = db(table).where("last_seen_at", ">", cutoff).orderBy([{ column: "service_group", order: "asc" }, { column: "service_name", order: "asc" }]);
+  if (options.serviceGroup?.trim()) {
+    q = q.where({ service_group: options.serviceGroup.trim() });
+  }
+  return await q;
+}
+
+// src/tasks/taskLogs.js
+var import_node_path = __toESM(require("path"), 1);
+function getLogsState(context) {
+  const holder = context;
+  if (holder.__tasksLogsState) return holder.__tasksLogsState;
+  const basePath = holder.params?.get?.("tasksLogsBasePath") || "./data";
+  const namespace = holder.params?.get?.("tasksLogsNamespace") || "tasks-logs";
+  const tableName = holder.params?.get?.("tasksLogsTable") || "runner";
+  const errorTableName = holder.params?.get?.("tasksErrorLogsTable") || `${tableName}-errors`;
+  const maxVersionsRaw = Number(holder.params?.get?.("tasksLogsMaxVersions"));
+  const pageSizeRaw = Number(holder.params?.get?.("tasksLogsPageSize"));
+  const errorDb = new FileDatabase({
+    basePath,
+    namespace,
+    tableName: errorTableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: Number.isFinite(maxVersionsRaw) && maxVersionsRaw > 0 ? maxVersionsRaw : 20,
+    pageSize: Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 2e3,
+    logger: holder.logger
+  });
+  const enabledRaw = holder.params?.get?.("tasksLogsEnabled");
+  const enabled = enabledRaw === void 0 ? true : !!enabledRaw;
+  if (!enabled) {
+    const disabledState = {
+      db: null,
+      errorDb,
+      queue: Promise.resolve(),
+      initialized: true,
+      errorInitialized: false
+    };
+    holder.__tasksLogsState = disabledState;
+    return disabledState;
+  }
+  const db = new FileDatabase({
+    basePath,
+    namespace,
+    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,
+    queue: Promise.resolve(),
+    initialized: false,
     errorInitialized: false
   };
   holder.__tasksLogsState = state;
   return state;
 }
+function ipcLogTargetKey(target) {
+  const bp = target.basePath ?? "";
+  const ns = target.namespace ?? "";
+  return `${bp}::${ns}::${target.tableName}`;
+}
+function ipcFileLogsTableNameForSourceResource(source, resource) {
+  const seg = (s) => {
+    const t = String(s).trim().replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+|_+$/g, "");
+    return t.length ? t : "x";
+  };
+  return `${seg(source)}/${seg(resource)}`;
+}
+async function readTaskIpcLogsSnapshot(context, options) {
+  const holder = context;
+  const basePath = holder.params?.get?.("tasksLogsBasePath") ?? "./data";
+  const namespace = holder.params?.get?.("tasksLogsNamespace") ?? "tasks-logs";
+  const tableName = ipcFileLogsTableNameForSourceResource(options.source, options.resource);
+  const tail = Math.max(1, Math.min(1e4, Number(options.tail) > 0 ? Number(options.tail) : 100));
+  const fd = new FileDatabase({
+    basePath,
+    namespace,
+    tableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: 30,
+    pageSize: 2e3,
+    logger: holder.logger
+  });
+  const versions = await fd.getVersions();
+  if (versions.length === 0) {
+    return { records: [], latestTs: null };
+  }
+  const latest = versions[versions.length - 1];
+  const raw = await fd.read({ version: latest });
+  const arr = Array.isArray(raw) ? raw : [];
+  let filtered = arr;
+  if (options.afterTs && String(options.afterTs).trim()) {
+    const cut = String(options.afterTs).trim();
+    filtered = arr.filter((r) => r && typeof r.ts === "string" && String(r.ts) > cut);
+  }
+  let latestTs = null;
+  for (const r of filtered) {
+    const ts = typeof r?.ts === "string" ? String(r.ts) : null;
+    if (ts && (!latestTs || ts > latestTs)) latestTs = ts;
+  }
+  const incremental = !!(options.afterTs && String(options.afterTs).trim());
+  const maxReturn = incremental ? 1e4 : tail;
+  const sliced = filtered.length > maxReturn ? filtered.slice(-maxReturn) : filtered;
+  return { records: sliced, latestTs };
+}
+function resolveIpcFileLogsDir(context, target) {
+  const holder = context;
+  const basePath = target.basePath ?? (holder.params?.get?.("tasksLogsBasePath") || "./data");
+  const namespace = target.namespace ?? (holder.params?.get?.("tasksLogsNamespace") || "tasks-logs");
+  const segments = target.tableName.split("/").filter(Boolean);
+  return import_node_path.default.resolve(basePath, namespace, ...segments);
+}
+function getLogsStateForTarget(context, target) {
+  const holder = context;
+  const enabledRaw = holder.params?.get?.("tasksLogsEnabled");
+  const enabled = enabledRaw === void 0 ? true : !!enabledRaw;
+  if (!enabled) return null;
+  if (!holder.__tasksLogsTargetStates) holder.__tasksLogsTargetStates = /* @__PURE__ */ new Map();
+  const map = holder.__tasksLogsTargetStates;
+  const key = ipcLogTargetKey(target);
+  if (map.has(key)) return map.get(key);
+  const basePath = target.basePath ?? (holder.params?.get?.("tasksLogsBasePath") || "./data");
+  const namespace = target.namespace ?? (holder.params?.get?.("tasksLogsNamespace") || "tasks-logs");
+  const maxVersionsRaw = Number(holder.params?.get?.("tasksLogsMaxVersions"));
+  const pageSizeRaw = Number(holder.params?.get?.("tasksLogsPageSize"));
+  const db = new FileDatabase({
+    basePath,
+    namespace,
+    tableName: target.tableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: Number.isFinite(maxVersionsRaw) && maxVersionsRaw > 0 ? maxVersionsRaw : 20,
+    pageSize: Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 2e3,
+    logger: holder.logger
+  });
+  const state = {
+    db,
+    errorDb: null,
+    queue: Promise.resolve(),
+    initialized: false,
+    errorInitialized: false
+  };
+  map.set(key, state);
+  return state;
+}
 function isErrorPayload(payload) {
   if (!payload) return false;
   if (typeof payload === "object") {
@@ -4286,14 +4921,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);
@@ -4310,84 +4957,293 @@ function appendTaskIpcLog(context, task, payload) {
     context.logger.warn?.("[tasks] failed to persist IPC log entry:", error);
   });
 }
-
-// src/tasks/time-matcher.ts
-var RANGES = ["0-59", "0-59", "0-23", "1-31", "1-12", "0-6"];
-function resolveAsterisks(field, range) {
-  return field.includes("*") ? field.replace("*", range) : field;
-}
-function resolveRanges(field) {
-  const regex = /(\d+)-(\d+)/;
-  let current = field;
-  while (true) {
-    const match = regex.exec(current);
-    if (!match) break;
-    const raw = match[0];
-    let first = Number(match[1]);
-    let last = Number(match[2]);
-    if (last < first) {
-      [first, last] = [last, first];
-    }
-    const values = [];
-    for (let i = first; i <= last; i += 1) {
-      values.push(i);
+async function flushTaskIpcLogs(context) {
+  const holder = context;
+  const promises = [];
+  if (holder.__tasksLogsState?.queue) promises.push(holder.__tasksLogsState.queue);
+  const map = holder.__tasksLogsTargetStates;
+  if (map) {
+    for (const s of map.values()) {
+      if (s.queue) promises.push(s.queue);
     }
-    current = current.replace(raw, values.join(","));
   }
-  return current;
-}
-function resolveSteps(field) {
-  const match = /^(.+)\/(\d+)$/.exec(field);
-  if (!match) return field;
-  const base = match[1];
-  const step = Number(match[2]);
-  if (!Number.isFinite(step) || step <= 0) return field;
-  return base.split(",").map((v) => Number(v)).filter((v) => Number.isFinite(v) && v % step === 0).join(",");
-}
-function convertPattern(pattern) {
-  const parts = pattern.trim().split(/\s+/);
-  if (parts.length !== 6) {
-    throw new Error(`Invalid schedule "${pattern}". Expected 6 fields: sec min hour day month weekday`);
-  }
-  return parts.map((field, idx) => resolveAsterisks(field, RANGES[idx])).map((field) => resolveRanges(field)).map((field) => resolveSteps(field));
-}
-function fieldMatches(field, value) {
-  const allowed = field.split(",").map((v) => Number(v));
-  return allowed.includes(value);
-}
-function timeMatcher(pattern, date = /* @__PURE__ */ new Date()) {
-  const parsed = convertPattern(pattern);
-  return fieldMatches(parsed[0], date.getSeconds()) && fieldMatches(parsed[1], date.getMinutes()) && fieldMatches(parsed[2], date.getHours()) && fieldMatches(parsed[3], date.getDate()) && fieldMatches(parsed[4], date.getMonth() + 1) && fieldMatches(parsed[5], date.getDay());
+  await Promise.all(promises);
 }
 
-// src/tasks/TaskMaster.ts
-var TaskMaster = class {
-  context;
-  task;
+// src/tasks/AbstractTask.js
+var AbstractTask = class _AbstractTask {
+  /**
+   * Whether `send-task` should wait for completion (and print a result
+   * report) when no explicit `--wait` / `--noWait` flag is given. Defaults
+   * to false; short-lived probe tasks (e.g. `ping`) override to true.
+   *
+   * @type {boolean}
+   */
+  static defaultWaitForResult = false;
+  /**
+   * @param {object} context Runner context (db, logger, params, emitter...).
+   * @param {object} task    Task row as claimed from the queue.
+   */
   constructor(context, task) {
     this.context = context;
     this.task = task;
   }
+  /**
+   * Return a short reason string when the task should be deferred (e.g. "locked
+   * by source"), or `false`/falsy when it is free to run. Default: always `false`.
+   *
+   * @returns {string | false | Promise<string | false>}
+   */
   cantRunReason() {
     return false;
   }
+  /**
+   * Called by the runner when a stop has been requested. Subclasses running
+   * long loops should flip a flag here and check it between iterations.
+   *
+   * @param {number} [_allowanceMs] Grace period the runner promises before hard exit.
+   */
   requestStop(_allowanceMs) {
   }
+  /**
+   * 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 defs = {
+      queueName: "string default tasks",
+      priority: "number default 50",
+      serviceGroup: "string",
+      serviceName: "string",
+      instanceNumber: "number",
+      serverName: "string",
+      opid: "string",
+      schedule: "string"
+    };
+    const cli = context.params.getAllForModule("task-envelope", defs);
+    const name = emptyToUndef(overrides.name) ?? emptyToUndef(context.params.get("name", "string"));
+    if (!name) {
+      throw new ParamError("Task --name is required (e.g. ping, stop, dummyHarvest)");
+    }
+    let instanceNumber;
+    const rawInstance = overrides.instanceNumber ?? cli.instanceNumber;
+    if (rawInstance !== void 0 && rawInstance !== null && String(rawInstance).trim() !== "") {
+      const n = Number(rawInstance);
+      if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1) {
+        throw new ParamError("--instanceNumber must be a positive integer when set");
+      }
+      instanceNumber = n;
+    } else {
+      instanceNumber = null;
+    }
+    const priorityRaw = overrides.priority ?? cli.priority ?? 50;
+    const priority = Number(priorityRaw);
+    if (!Number.isFinite(priority)) {
+      throw new ParamError(`--priority must be a number (got ${JSON.stringify(priorityRaw)})`);
+    }
+    return {
+      name,
+      queueName: overrides.queueName ?? emptyToUndef(cli.queueName) ?? "tasks",
+      priority,
+      serviceGroup: emptyToUndef(overrides.serviceGroup) ?? emptyToUndef(cli.serviceGroup) ?? null,
+      serviceName: emptyToUndef(overrides.serviceName) ?? emptyToUndef(cli.serviceName) ?? null,
+      instanceNumber,
+      serverName: emptyToUndef(overrides.serverName) ?? emptyToUndef(cli.serverName) ?? null,
+      opid: emptyToUndef(overrides.opid) ?? emptyToUndef(cli.opid) ?? null,
+      schedule: emptyToUndef(overrides.schedule) ?? emptyToUndef(cli.schedule) ?? null,
+      nextRunAt: overrides.nextRunAt ?? null
+    };
+  }
+  /**
+   * Default inner-params resolver: parses `--paramsJson` (must be a JSON
+   * object), then overlays `overrides.params` on top. Returns `null` when
+   * neither is provided.
+   *
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {object|null}
+   */
+  static _defaultParamsBlob(context, overrides = {}) {
+    const cli = context.params.getAllForModule("task-params", { paramsJson: "string" });
+    const fromJson = parseParamsJson(cli.paramsJson);
+    const fromOverride = pickParamsObject(overrides);
+    if (!fromJson && !fromOverride) return null;
+    return { ...fromJson ?? {}, ...fromOverride ?? {} };
+  }
+  /**
+   * Helper for subclass `resolveCustomParams` overrides. Reads typed CLI
+   * params (per `defs`) plus `--paramsJson` under a module namespace, then
+   * merges them with explicit `overrides.params` in increasing priority:
+   *
+   *   typed CLI flags → --paramsJson → overrides.params
+   *
+   * Undefined values are dropped so defaults declared in `defs` aren't
+   * overwritten by missing-flag noise. Returns the merged object; the
+   * caller is responsible for validation and throwing `ParamError`.
+   *
+   * @param {object} context
+   * @param {string} moduleName Namespace for `--showUsedParams` grouping.
+   * @param {Record<string, string>} defs Param defs in `getAllForModule` syntax.
+   * @param {Record<string, unknown>} [overrides] As passed to `resolveCustomParams`.
+   * @returns {Record<string, unknown>}
+   */
+  static _mergeTypedParams(context, moduleName, defs, overrides = {}) {
+    const fullDefs = { ...defs, paramsJson: "string" };
+    const cliRaw = context.params.getAllForModule(moduleName, fullDefs);
+    const fromJson = parseParamsJson(cliRaw.paramsJson) ?? {};
+    const fromCli = {};
+    for (const [k, v] of Object.entries(cliRaw)) {
+      if (k === "paramsJson") continue;
+      if (v !== void 0 && v !== null) fromCli[k] = v;
+    }
+    const fromOverride = pickParamsObject(overrides) ?? {};
+    return { ...fromCli, ...fromJson, ...fromOverride };
+  }
 };
+function emptyToUndef(s) {
+  if (s === void 0 || s === null) return void 0;
+  if (typeof s !== "string") return s;
+  const t = s.trim();
+  return t.length ? t : void 0;
+}
+function parseParamsJson(raw) {
+  if (raw == null) return null;
+  const t = String(raw).trim();
+  if (!t) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(t);
+  } catch (e) {
+    throw new ParamError(`--paramsJson: not valid JSON: ${e?.message ?? String(e)}`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new ParamError("--paramsJson must be a JSON object");
+  }
+  return parsed;
+}
+function pickParamsObject(overrides) {
+  const p = overrides?.params;
+  if (p && typeof p === "object" && !Array.isArray(p)) return p;
+  return void 0;
+}
 
-// src/tasks/coreTasks/TaskPing.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;
@@ -4395,6 +5251,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;
@@ -4476,7 +5340,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) => {
@@ -4506,7 +5370,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;
@@ -4555,8 +5439,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`;
@@ -4575,13 +5459,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;
@@ -4607,10 +5500,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})`);
@@ -4627,8 +5520,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;
@@ -4659,8 +5575,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})`);
@@ -4675,175 +5629,399 @@ var TaskStopRunner = class extends TaskMaster {
   }
 };
 
-// src/tasks/TasksRegistry.ts
+// src/tasks/coreTasks/TaskGetLogs.js
+var TaskGetLogs = class extends AbstractTask {
+  /**
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<{ source: string, resource: string, tail: number, afterTs?: string }>}
+   */
+  static async resolveCustomParams(context, overrides = {}) {
+    const merged = AbstractTask._mergeTypedParams(context, "task-get-logs", {
+      source: "string",
+      resource: "string",
+      tail: "number default 100",
+      afterTs: "string"
+    }, overrides);
+    const source = typeof merged.source === "string" ? merged.source.trim() : "";
+    const resource = typeof merged.resource === "string" ? merged.resource.trim() : "";
+    if (!source) throw new ParamError('getLogs: param "source" is required');
+    if (!resource) throw new ParamError('getLogs: param "resource" is required');
+    let tail = Number(merged.tail);
+    if (!Number.isFinite(tail) || tail < 1) tail = 100;
+    tail = Math.min(1e4, Math.max(1, Math.floor(tail)));
+    const out = { source, resource, tail };
+    if (typeof merged.afterTs === "string" && merged.afterTs.trim()) {
+      out.afterTs = merged.afterTs.trim();
+    }
+    return out;
+  }
+  /**
+   * @param {unknown} _reportProgress Unused (single-shot read, no progress events).
+   * @returns {Promise<{ success: boolean, results: unknown }>}
+   */
+  async run(_reportProgress) {
+    const p = this.task.params ?? {};
+    const source = String(p.source ?? "").trim();
+    const resource = String(p.resource ?? "").trim();
+    const tail = Math.max(1, Math.min(1e4, Number(p.tail) > 0 ? Number(p.tail) : 100));
+    const afterTs = p.afterTs != null && String(p.afterTs).trim() ? String(p.afterTs).trim() : null;
+    if (!source || !resource) {
+      return {
+        success: false,
+        results: { error: 'getLogs requires params "source" and "resource"' }
+      };
+    }
+    try {
+      const { records, latestTs } = await readTaskIpcLogsSnapshot(this.context, {
+        source,
+        resource,
+        tail,
+        afterTs
+      });
+      return {
+        success: true,
+        results: { records, latestTs, source, resource }
+      };
+    } catch (e) {
+      return {
+        success: false,
+        results: { error: e?.message ?? String(e) }
+      };
+    }
+  }
+};
+
+// src/tasks/TasksRegistry.js
 var TasksRegistry = class _TasksRegistry {
-  map = {};
+  /**
+   * @param {Record<string, Function>} [initial] Optional seed entries to copy in.
+   */
   constructor(initial) {
+    this.map = {};
     if (initial) {
       this.addMany(initial);
     }
   }
+  /**
+   * Build a registry pre-populated with every core task plus legacy aliases.
+   * Prefer this over `new TasksRegistry()` for anything that wants `ping`/`stop`/etc.
+   *
+   * @returns {TasksRegistry}
+   */
   static withCoreTasks() {
-    return new _TasksRegistry().add("ping", TaskPing).add("sampleProcess", TaskSampleProcess).add("shellCommand", TaskShellCommand).add("systemInfo", TaskSystemInfo).add("taskSumAB", TaskSumAB).add("stopRunner", TaskStopRunner).add("stop", TaskStopRunner);
+    return new _TasksRegistry().add("ping", TaskPing).add("sampleProcess", TaskSampleProcess).add("shellCommand", TaskShellCommand).add("systemInfo", TaskSystemInfo).add("info", TaskSystemInfo).add("taskSumAB", TaskSumAB).add("stopRunner", TaskStopRunner).add("stop", TaskStopRunner).add("getLogs", TaskGetLogs);
   }
+  /**
+   * Register a single task class under a name. Overwrites any previous entry.
+   *
+   * @param {string} taskName
+   * @param {Function} taskClass Subclass of `AbstractTask`.
+   * @returns {this}
+   */
   add(taskName, taskClass) {
     this.map[taskName] = taskClass;
     return this;
   }
+  /**
+   * Bulk-register a name → class map. Later calls override earlier ones.
+   *
+   * @param {Record<string, Function>} entries
+   * @returns {this}
+   */
   addMany(entries) {
     for (const [name, klass] of Object.entries(entries)) {
       this.add(name, klass);
     }
     return this;
   }
+  /**
+   * Look up a task class by name. Returns `undefined` when the name is unknown;
+   * the runner treats that as "some other worker may handle this" and skips.
+   *
+   * @param {string} taskName
+   * @returns {Function | undefined}
+   */
   get(taskName) {
     return this.map[taskName];
   }
+  /**
+   * Strict variant of {@link get}: throws {@link ParamError} (with the list
+   * of supported names) when `taskName` is unknown. Use from enqueuer code
+   * paths where an unknown name is a hard CLI/programmer error.
+   *
+   * @param {string} taskName
+   * @returns {Function}
+   */
+  requireClass(taskName) {
+    const TaskClass = taskName ? this.map[taskName] : void 0;
+    if (!TaskClass) {
+      const supported = this.listSupportedTasks().join(", ") || "(none)";
+      throw new ParamError(
+        `Unknown task "${taskName ?? ""}". Supported on this registry: ${supported}`
+      );
+    }
+    return TaskClass;
+  }
+  /**
+   * Dispatcher used by `send-task` / programmatic enqueuers: pick `name`
+   * from `overrides` or `context.params`, look up the class, and delegate
+   * to its static {@link AbstractTask.resolveParams} with `name` seeded into
+   * the overrides. The returned object is shaped for {@link enqueueTask}.
+   *
+   * Validation failures (unknown task, missing required custom params, etc.)
+   * surface as {@link ParamError} so the caller aborts cleanly before any
+   * row is inserted.
+   *
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<object>}
+   */
+  async resolveTaskParams(context, overrides = {}) {
+    const overrideName = typeof overrides.name === "string" ? overrides.name.trim() : overrides.name;
+    const fromCli = context.params.get("name", "string");
+    const cliName = typeof fromCli === "string" ? fromCli.trim() : fromCli;
+    const name = overrideName || cliName;
+    if (!name) {
+      throw new ParamError("Task --name is required (e.g. ping, stop, dummyHarvest)");
+    }
+    const TaskClass = this.requireClass(name);
+    return TaskClass.resolveParams(context, { ...overrides, name });
+  }
+  /**
+   * Names of every registered task, sorted alphabetically (useful for CLI output
+   * and allowlist sanity checks).
+   *
+   * @returns {string[]}
+   */
   listSupportedTasks() {
     return Object.keys(this.map).sort();
   }
+  /**
+   * Shallow copy of the internal map, for handing to `addMany` on another registry
+   * or for serialization.
+   *
+   * @returns {Record<string, Function>}
+   */
   toObject() {
     return { ...this.map };
   }
 };
 
-// src/tasks/taskScriptRunner.ts
+// src/tasks/serviceTaskAllowlist.js
+var SERVICE_TASK_NAMES = [
+  "ping",
+  "stop",
+  "stopRunner",
+  "shellCommand",
+  "systemInfo",
+  "info",
+  "getLogs"
+];
+function normalizeAllowedTasks(value) {
+  if (!value) return void 0;
+  if (Array.isArray(value)) {
+    const out2 = value.map((v) => String(v).trim()).filter(Boolean);
+    return out2.length ? out2 : void 0;
+  }
+  const out = String(value).split(",").map((v) => v.trim()).filter(Boolean);
+  return out.length ? out : void 0;
+}
+function mergeAllowedTasksWithServiceTasks(names) {
+  const set = /* @__PURE__ */ new Set([...SERVICE_TASK_NAMES, ...names ?? []]);
+  return Array.from(set).sort();
+}
+
+// src/tasks/taskScriptRunner.js
 var import_node_child_process2 = require("child_process");
+var MAX_PROGRESS_TEXT_LEN = 4e3;
 function toCliArgs(args = []) {
   return args.filter((a) => typeof a === "string" && a.length > 0);
 }
 function formatChildLogPrefix(task) {
-  return `${task.task}:${task.id.slice(0, 8)}${task.opid ? `:${task.opid}` : ""}`;
+  return `${task.name}:${task.id.slice(0, 8)}${task.opid ? `:${task.opid}` : ""}`;
 }
-async function runNodeTaskScript(context, options) {
-  const cliArgs = toCliArgs(["--route=ipc", "--mode=json", ...options.args || []]);
+function isProgressPayload(payload) {
+  if (!payload || typeof payload !== "object") return false;
+  if (payload.level !== "progress") return false;
+  const count = Number(payload.count);
+  const total = Number(payload.total);
+  return Number.isFinite(count) && Number.isFinite(total) && total > 0;
+}
+function formatProgressText(payload, fallbackPrefix) {
+  const pfx = payload.prefix ? `${payload.prefix} ` : fallbackPrefix ? `${fallbackPrefix} ` : "";
+  const label = typeof payload.message === "string" && payload.message ? `${payload.message} ` : "";
+  return `${pfx}${label}${payload.count}/${payload.total}`;
+}
+function forwardChildLogToParent(context, prefix, message) {
+  if (!message || typeof message !== "object") return;
+  const text = typeof message.message === "string" ? message.message : null;
+  if (!text) return;
+  const level = typeof message.level === "string" ? message.level.toLowerCase() : "";
+  const line = `[child:${prefix}] ${text}`;
+  const logger = context.logger;
+  switch (level) {
+    case "error":
+    case "fatal":
+      logger.error?.(line);
+      return;
+    case "warn":
+    case "warning":
+      logger.warn?.(line);
+      return;
+    case "debug":
+      logger.debug?.(line);
+      return;
+    case "info":
+    default:
+      logger.info?.(line);
+  }
+}
+function buildNodeArgs(scriptPath, cliArgs) {
   const inheritedExecArgs = Array.isArray(process.execArgv) ? [...process.execArgv] : [];
   const hasTsRuntimeInParent = inheritedExecArgs.some((arg) => /tsx|ts-node/i.test(arg));
-  const nodeArgs = hasTsRuntimeInParent ? [...inheritedExecArgs, options.scriptPath, ...cliArgs] : ["--import", "tsx", options.scriptPath, ...cliArgs];
-  const child = (0, import_node_child_process2.spawn)(
-    process.execPath,
-    nodeArgs,
-    {
-      cwd: options.cwd || process.cwd(),
-      stdio: ["ignore", "pipe", "pipe", "ipc"],
-      env: {
-        ...process.env,
-        TASK_ID: options.task.id,
-        TASK_NAME: options.task.task,
-        TASK_OPID: options.task.opid || ""
-      }
-    }
+  return hasTsRuntimeInParent ? [...inheritedExecArgs, scriptPath, ...cliArgs] : ["--import", "tsx", scriptPath, ...cliArgs];
+}
+function resolveTasksTableName(context) {
+  return context.tasksQueueName || context.params?.get?.("table") || "tasks";
+}
+function announceIpcFileLogsTarget(context, options) {
+  if (!options.ipcFileLogs) return;
+  const logsDir = resolveIpcFileLogsDir(context, options.ipcFileLogs);
+  const enabledRaw = context.params?.get?.("tasksLogsEnabled");
+  const logsEnabled = enabledRaw === void 0 ? true : !!enabledRaw;
+  context.logger.info?.(
+    `[tasks] IPC file logs: ${logsDir}` + (logsEnabled ? "" : " (tasksLogsEnabled=false; not persisted)")
   );
-  let stdout = "";
-  let stderr = "";
-  let workerResult = null;
-  let hadErrorMessage = false;
-  const prefix = formatChildLogPrefix(options.task);
-  const db = context.db;
-  const tasksTable = context.params?.get?.("table") || "tasks";
-  let progressWriteChain = Promise.resolve();
-  let progressCallbackChain = Promise.resolve();
-  const updateProgress = (text) => {
-    if (!db || !text || !text.trim()) return;
-    progressWriteChain = progressWriteChain.then(async () => {
-      await db(tasksTable).where({ id: options.task.id }).update({ progress: text.slice(0, 4e3) });
-    }).catch((error) => {
-      context.logger.warn?.(
-        `[tasks] failed to update progress for task=${options.task.id}: ${error?.message ?? String(error)}`
-      );
-    });
-    if (options.onProgress) {
-      progressCallbackChain = progressCallbackChain.then(async () => {
-        await options.onProgress?.(text.slice(0, 4e3));
-      }).catch((error) => {
-        context.logger.warn?.(
-          `[tasks] reportProgress callback failed for task=${options.task.id}: ${error?.message ?? String(error)}`
-        );
+}
+function createSerializedQueue() {
+  let chain = Promise.resolve();
+  return {
+    push(fn) {
+      chain = chain.then(fn, () => {
+      }).catch(() => {
+      });
+      return chain;
+    },
+    drain() {
+      return chain.catch(() => {
       });
     }
   };
-  const payloadToProgressText = (payload) => {
-    if (!payload) return "";
-    if (typeof payload === "string") return payload;
-    if (typeof payload.message === "string" && payload.level === "progress" && payload.count !== void 0 && payload.total !== void 0) {
-      const pfx = payload.prefix ? `${payload.prefix} ` : "";
-      return `${pfx}${payload.message} ${payload.count}/${payload.total}`;
-    }
-    if (typeof payload.message === "string") return payload.message;
-    if (payload.level === "progress" && payload.count !== void 0 && payload.total !== void 0) {
-      const pfx = payload.prefix ? `${payload.prefix} ` : "";
-      return `${pfx}${payload.count}/${payload.total}`;
-    }
-    return "";
+}
+async function runNodeTaskScript(context, options) {
+  const cliArgs = toCliArgs(["--route=ipc", "--mode=json", ...options.args || []]);
+  const nodeArgs = buildNodeArgs(options.scriptPath, cliArgs);
+  const child = (0, import_node_child_process2.spawn)(process.execPath, nodeArgs, {
+    cwd: options.cwd || process.cwd(),
+    stdio: ["ignore", "pipe", "pipe", "ipc"],
+    env: {
+      ...process.env,
+      TASK_ID: options.task.id,
+      TASK_NAME: options.task.name,
+      TASK_OPID: options.task.opid || ""
+    }
+  });
+  announceIpcFileLogsTarget(context, options);
+  const prefix = formatChildLogPrefix(options.task);
+  const tasksTable = resolveTasksTableName(context);
+  const progressQueue = createSerializedQueue();
+  const state = {
+    stdout: "",
+    stderr: "",
+    workerResult: null,
+    hadErrorMessage: false
+  };
+  const writeProgress = (text) => {
+    const trimmed = typeof text === "string" ? text.slice(0, MAX_PROGRESS_TEXT_LEN) : "";
+    if (!trimmed) return;
+    progressQueue.push(async () => {
+      const db = context.db;
+      if (db) {
+        try {
+          await db(tasksTable).where({ id: options.task.id }).update({ progress: trimmed });
+        } catch (error) {
+          context.logger.warn?.(
+            `[tasks] failed to update progress for task=${options.task.id}: ${error?.message ?? String(error)}`
+          );
+        }
+      }
+      if (options.onProgress) {
+        try {
+          await options.onProgress(trimmed);
+        } catch (error) {
+          context.logger.warn?.(
+            `[tasks] reportProgress callback failed for task=${options.task.id}: ${error?.message ?? String(error)}`
+          );
+        }
+      }
+    });
   };
-  child.stdout.on("data", (chunk) => {
+  child.stdout?.on("data", (chunk) => {
     const text = String(chunk);
-    stdout += text;
+    state.stdout += text;
     if (text.trim()) {
       context.logger.info?.(`[child:${prefix}] ${text.trimEnd()}`);
-      updateProgress(text.trim().replace(/\s+/g, " ").slice(0, 400));
     }
   });
-  child.stderr.on("data", (chunk) => {
+  child.stderr?.on("data", (chunk) => {
     const text = String(chunk);
-    stderr += text;
+    state.stderr += text;
     if (text.trim()) {
       context.logger.warn?.(`[child:${prefix}] ${text.trimEnd()}`);
     }
   });
   child.on("message", (message) => {
     if (message && typeof message === "object" && "__taskWorkerResult" in message) {
-      workerResult = message.__taskWorkerResult;
+      state.workerResult = message.__taskWorkerResult;
       return;
     }
     if (message && typeof message === "object") {
       const level = typeof message.level === "string" ? message.level.toLowerCase() : "";
       if (level === "error" || level === "fatal") {
-        hadErrorMessage = true;
+        state.hadErrorMessage = true;
       }
     }
-    appendTaskIpcLog(context, options.task, message);
-    const progressText = payloadToProgressText(message);
-    if (progressText) {
-      updateProgress(progressText);
-      if (typeof message === "object" && message?.level === "progress" && message.count !== void 0 && message.total !== void 0) {
-        const countNum = Number(String(message.count).trim());
-        const totalNum = Number(message.total);
-        if (Number.isFinite(countNum) && Number.isFinite(totalNum) && totalNum > 0) {
-          context.logger.progress(message.message || "progress", {
-            prefix: message.prefix || prefix,
-            count: countNum,
-            total: totalNum
-          });
-        } else {
-          context.logger.info?.(`[child:${prefix}] ${progressText}`);
-        }
-      } else {
-        context.logger.info?.(`[child:${prefix}] ${progressText}`);
-      }
+    appendTaskIpcLog(context, options.task, message, options.ipcFileLogs);
+    try {
+      options.onChildIpcMessage?.(message);
+    } catch (e) {
+      context.logger.warn?.(`[tasks] onChildIpcMessage failed: ${e?.message ?? String(e)}`);
     }
+    if (isProgressPayload(message)) {
+      context.logger.progress(message.message || "progress", {
+        prefix: message.prefix || prefix,
+        count: Number(message.count),
+        total: Number(message.total)
+      });
+      writeProgress(formatProgressText(message, prefix));
+      return;
+    }
+    forwardChildLogToParent(context, prefix, message);
   });
   return await new Promise((resolve2, reject) => {
     child.on("error", (error) => reject(error));
     child.on("close", (exitCode, signal) => {
-      Promise.allSettled([progressWriteChain, progressCallbackChain]).finally(() => {
+      void (async () => {
+        await flushTaskIpcLogs(context);
+        await progressQueue.drain();
         resolve2({
           exitCode,
           signal,
-          stdout: stdout.trim(),
-          stderr: stderr.trim(),
-          workerResult,
-          hadErrorMessage
+          stdout: state.stdout.trim(),
+          stderr: state.stderr.trim(),
+          workerResult: state.workerResult,
+          hadErrorMessage: state.hadErrorMessage
         });
-      });
+      })();
     });
   });
 }
 
-// src/tasks/index.ts
+// src/tasks/index.js
 var LOCKED_BY_ERROR_MESSAGE = "locked by error";
 var defaultTasksRegistry = TasksRegistry.withCoreTasks();
-function getDb2(context) {
+function getDb3(context) {
   const db = context.db;
   if (!db) {
     throw new Error("Tasks component requires context.db. Initialize DB first and attach to context.");
@@ -4855,22 +6033,13 @@ function normalizeRegistry(registry) {
   if (registry instanceof TasksRegistry) return registry;
   return new TasksRegistry().addMany(registry);
 }
-function normalizeAllowedTasks(value) {
-  if (!value) return void 0;
-  if (Array.isArray(value)) {
-    const out2 = value.map((v) => String(v).trim()).filter(Boolean);
-    return out2.length ? out2 : void 0;
-  }
-  const out = String(value).split(",").map((v) => v.trim()).filter(Boolean);
-  return out.length ? out : void 0;
-}
-async function enqueueStopTask(context, target, queue = "tasks", allowanceMs = 5e3) {
+async function enqueueStopTask(context, serviceGroup, queueName = "tasks", allowanceMs = 5e3) {
   return enqueueTask(context, {
-    queue,
-    target,
-    task: "stopRunner",
+    queueName,
+    name: "stopRunner",
     params: { allowanceMs },
-    priority: 1e6
+    priority: 0,
+    serviceGroup
   });
 }
 async function signalRunningTasksStop(context, runningTaskInstances, allowanceMs) {
@@ -4887,19 +6056,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,
@@ -4907,7 +6078,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 {
@@ -4934,13 +6106,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");
@@ -4955,19 +6130,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({
@@ -4975,7 +6163,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
       });
@@ -4987,208 +6176,400 @@ 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 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 }).whereNull("started_at").whereNull("paused_at").update({ started_at: db.fn.now() }).returning("*");
+    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,
-          historyTable,
-          claimedStopTask,
+          target,
           registry,
-          runningTaskInstances
-        ).then(async (outcome) => {
+          10,
+          ["stopRunner", "stop"],
+          runnerIdentity
+        );
+        if (claimedStopTask) {
+          runningStopControlPromise = executeClaimedTask(
+            context,
+            tasksTable,
+            historyTable,
+            claimedStopTask,
+            registry,
+            runningTaskInstances
+          ).then(async (outcome) => {
+            if (outcome.stopRunnerRequested && !stopRequested) {
+              stopRequested = true;
+              stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
+              context.tasksRunnerStop = true;
+              await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
+            }
+          }).finally(() => {
+            runningStopControlPromise = null;
+          });
+        }
+      }
+      if (claimJitterMs > 0) {
+        await sleepMs(Math.floor(Math.random() * (claimJitterMs + 1)));
+      }
+      while (runningPromises.size < maxParallel) {
+        const claimed = await claimNextRunnableTask(
+          context,
+          tasksTable,
+          target,
+          registry,
+          scanLimit,
+          allowedTasks,
+          runnerIdentity
+        );
+        if (!claimed) break;
+        const p = executeClaimedTask(context, tasksTable, historyTable, claimed, registry, runningTaskInstances).then(async (outcome) => {
           if (outcome.stopRunnerRequested && !stopRequested) {
             stopRequested = true;
             stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
-            context.__tasksRunnerStop = true;
+            context.tasksRunnerStop = true;
             await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
           }
         }).finally(() => {
-          runningStopControlPromise = null;
+          runningPromises.delete(p);
         });
+        runningPromises.add(p);
+      }
+      const wakePromises = [...runningPromises];
+      if (runningStopControlPromise) {
+        wakePromises.push(runningStopControlPromise);
+      }
+      if (wakePromises.length === 0) {
+        await sleepMs(pollMs);
+      } else {
+        const safe = wakePromises.map((p) => p.catch(() => void 0));
+        await Promise.race([sleepMs(pollMs), Promise.race(safe)]);
       }
     }
-    while (runningPromises.size < maxParallel) {
-      const claimed = await claimNextRunnableTask(
-        context,
-        tasksTable,
-        target,
-        registry,
-        scanLimit,
-        allowedTasks
-      );
-      if (!claimed) break;
-      const p = executeClaimedTask(context, tasksTable, historyTable, claimed, registry, runningTaskInstances).then(async (outcome) => {
-        if (outcome.stopRunnerRequested && !stopRequested) {
-          stopRequested = true;
-          stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
-          context.__tasksRunnerStop = true;
-          await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
-        }
-      }).finally(() => {
-        runningPromises.delete(p);
-      });
-      runningPromises.add(p);
+    if (context.isStop() && !stopRequested) {
+      await signalRunningTasksStop(context, runningTaskInstances, 5e3);
     }
-    await sleepMs(pollMs);
-  }
-  if (context.isStop() && !stopRequested) {
-    await signalRunningTasksStop(context, runningTaskInstances, 5e3);
-  }
-  if (runningPromises.size > 0) {
-    if (stopRequested) {
-      await Promise.race([
-        Promise.allSettled(Array.from(runningPromises)),
-        sleepMs(stopAllowanceMs).then(() => {
-          context.logger.warn?.(
-            `[tasks] stop allowance (${stopAllowanceMs}ms) reached; ${runningPromises.size} task(s) still running`
-          );
-        })
-      ]);
-    } else {
-      await Promise.allSettled(Array.from(runningPromises));
+    if (runningPromises.size > 0) {
+      if (stopRequested) {
+        await Promise.race([
+          Promise.allSettled(Array.from(runningPromises)),
+          sleepMs(stopAllowanceMs).then(() => {
+            context.logger.warn?.(
+              `[tasks] stop allowance (${stopAllowanceMs}ms) reached; ${runningPromises.size} task(s) still running`
+            );
+          })
+        ]);
+      } else {
+        await Promise.allSettled(Array.from(runningPromises));
+      }
+    }
+  } finally {
+    if (registryInterval) {
+      clearInterval(registryInterval);
+      registryInterval = null;
+    }
+    if (registryReg) {
+      await unregisterServicesRegistry(context, registryReg).catch((err) => {
+        context.logger.warn?.(`[services-registry] unregister failed: ${err?.message ?? String(err)}`);
+      });
+      registryReg = null;
+      delete context.servicesRegistry;
+      delete context.runnerHeartbeat;
     }
   }
 }
 async function waitForTaskResult(context, taskId, options = {}) {
-  const db = getDb2(context);
-  const queue = options.queue ?? "tasks";
+  const db = getDb3(context);
+  const queueName = options.queueName ?? "tasks";
   const timeoutMs = options.timeoutMs ?? 6e4;
   const pollMs = options.pollMs ?? 500;
-  const { tasksTable, historyTable } = queueToTableNames(queue);
+  const { tasksTable, historyTable } = queueToTableNames(queueName);
   const deadline = Date.now() + timeoutMs;
+  const waitStartedAt = /* @__PURE__ */ new Date();
+  let cachedNameOpid = null;
+  async function historySinceWait(name, opid) {
+    let q = db(historyTable).where({ name }).where("completed_at", ">=", waitStartedAt);
+    if (opid == null || opid === "") {
+      q = q.whereNull("opid");
+    } else {
+      q = q.where({ opid });
+    }
+    return await q.orderBy("completed_at", "desc").first();
+  }
   while (Date.now() <= deadline) {
-    const done = await db(historyTable).where({ id: taskId }).orderBy("created_at", "desc").first();
-    if (done) return done;
+    const legacy = await db(historyTable).where({ id: taskId }).orderBy("created_at", "desc").first();
+    if (legacy) {
+      return legacy;
+    }
     const pending = await db(tasksTable).where({ id: taskId }).first();
-    if (!pending) {
-      const maybeDone = await db(historyTable).where({ id: taskId }).orderBy("created_at", "desc").first();
-      return maybeDone ?? null;
+    if (pending) {
+      cachedNameOpid = { name: pending.name, opid: pending.opid };
+      const done = await historySinceWait(pending.name, pending.opid);
+      if (done) {
+        return done;
+      }
+    } else if (cachedNameOpid) {
+      const done = await historySinceWait(cachedNameOpid.name, cachedNameOpid.opid);
+      if (done) {
+        return done;
+      }
+      return null;
+    } else {
+      return null;
     }
     await sleepMs(pollMs);
   }
   return null;
 }
 var TasksManager = class _TasksManager {
-  context;
-  queue;
-  target;
-  recreateTaskTables;
-  pollMs;
-  maxParallel;
-  scanLimit;
-  allowedTasks;
-  registry;
+  /**
+   * @param {object} context
+   * @param {{
+   *   queueName?: string,
+   *   target?: string,
+   *   recreateTaskTables?: boolean,
+   *   pollMs?: number,
+   *   claimJitterMs?: number,
+   *   maxParallel?: number,
+   *   scanLimit?: number,
+   *   allowedTasks?: string | string[],
+   *   registry?: TasksRegistry | Record<string, Function>,
+   *   runnerServiceGroup?: string,
+   *   runnerServiceName?: string,
+   *   runnerInstanceNumber?: number,
+   *   runnerHeartbeatIntervalMs?: number,
+   *   runnerHeartbeatStaleMs?: number,
+   *   runnerGroupMaxInstances?: number,
+   *   runnerEnforceMaxInstances?: boolean,
+   *   runnerMetadata?: Record<string, unknown>,
+   * }} [options]
+   */
   constructor(context, options = {}) {
     this.context = context;
-    this.queue = options.queue ?? "tasks";
+    this.queueName = options.queueName ?? "tasks";
     this.target = options.target ?? "localRunner";
     this.recreateTaskTables = options.recreateTaskTables ?? false;
     this.pollMs = options.pollMs ?? 1e3;
+    this.claimJitterMs = options.claimJitterMs ?? 0;
     this.maxParallel = options.maxParallel ?? 1;
     this.scanLimit = options.scanLimit ?? 100;
     this.allowedTasks = normalizeAllowedTasks(options.allowedTasks);
     this.registry = normalizeRegistry(options.registry);
+    this.runnerServiceGroup = options.runnerServiceGroup;
+    this.runnerServiceName = options.runnerServiceName;
+    this.runnerInstanceNumber = options.runnerInstanceNumber;
+    this.runnerHeartbeatIntervalMs = options.runnerHeartbeatIntervalMs;
+    this.runnerHeartbeatStaleMs = options.runnerHeartbeatStaleMs;
+    this.runnerGroupMaxInstances = options.runnerGroupMaxInstances;
+    this.runnerEnforceMaxInstances = options.runnerEnforceMaxInstances;
+    this.runnerMetadata = options.runnerMetadata;
   }
+  /**
+   * Preferred factory: reads defaults from `context.params` (module namespace
+   * `"tasks"`), then overlays explicit `options`. Keeps CLI flags, env vars,
+   * and inline options in one consistent resolver.
+   *
+   * @param {object} context
+   * @param {ConstructorParameters<typeof TasksManager>[1]} [options]
+   * @returns {TasksManager}
+   */
   static init(context, options = {}) {
     const defs = {
       table: "string default tasks",
       target: "string default localRunner",
       recreateTaskTables: "boolean default false",
       pollMs: "number default 1000",
+      claimJitterMs: "number default 0",
       maxParallel: "number default 1",
       scanLimit: "number default 100",
-      allowedTasks: "string"
+      allowedTasks: "string",
+      runnerServiceGroup: "string",
+      runnerServiceName: "string",
+      runnerInstanceNumber: "number",
+      runnerHeartbeatIntervalMs: "number default 10000",
+      runnerHeartbeatStaleMs: "number default 45000",
+      runnerGroupMaxInstances: "number",
+      runnerEnforceMaxInstances: "boolean default true"
     };
-    const discovered = context.params.getAllForModule(defs);
+    const discovered = context.params.getAllForModule("tasks", defs);
     const resolved = {
-      queue: discovered.table,
+      queueName: discovered.table,
       target: discovered.target,
       recreateTaskTables: discovered.recreateTaskTables,
       pollMs: discovered.pollMs,
+      claimJitterMs: discovered.claimJitterMs,
       maxParallel: discovered.maxParallel,
       scanLimit: discovered.scanLimit,
       allowedTasks: discovered.allowedTasks,
+      runnerServiceGroup: discovered.runnerServiceGroup,
+      runnerServiceName: discovered.runnerServiceName,
+      runnerInstanceNumber: discovered.runnerInstanceNumber,
+      runnerHeartbeatIntervalMs: discovered.runnerHeartbeatIntervalMs,
+      runnerHeartbeatStaleMs: discovered.runnerHeartbeatStaleMs,
+      runnerGroupMaxInstances: discovered.runnerGroupMaxInstances,
+      runnerEnforceMaxInstances: discovered.runnerEnforceMaxInstances,
       ...options
     };
     return new _TasksManager(context, resolved);
   }
+  /**
+   * Idempotently ensure the three backing tables exist for this queue.
+   *
+   * @param {{ recreate?: boolean }} [options]
+   * @returns {Promise<void>}
+   */
   async ensureTaskTables(options = {}) {
     await ensureTaskTables(this.context, {
-      queue: this.queue,
+      queueName: this.queueName,
       recreate: options.recreate ?? this.recreateTaskTables
     });
   }
+  /**
+   * Start the runner loop using this manager's resolved config. Per-call
+   * options override the stored defaults, but `runnerMetadata` still falls
+   * through when omitted.
+   *
+   * @param {Partial<ConstructorParameters<typeof TasksManager>[1]>} [options]
+   * @returns {Promise<void>}
+   */
   async runTasksLoop(options = {}) {
     await runTasksLoop(this.context, {
-      queue: options.queue ?? this.queue,
+      queueName: options.queueName ?? this.queueName,
       target: options.target ?? this.target,
       pollMs: options.pollMs ?? this.pollMs,
+      claimJitterMs: options.claimJitterMs ?? this.claimJitterMs,
       maxParallel: options.maxParallel ?? this.maxParallel,
       scanLimit: options.scanLimit ?? this.scanLimit,
       allowedTasks: options.allowedTasks ?? this.allowedTasks,
-      registry: options.registry ?? this.registry
+      registry: options.registry ?? this.registry,
+      runnerServiceGroup: options.runnerServiceGroup ?? this.runnerServiceGroup,
+      runnerServiceName: options.runnerServiceName ?? this.runnerServiceName,
+      runnerInstanceNumber: options.runnerInstanceNumber ?? this.runnerInstanceNumber,
+      runnerHeartbeatIntervalMs: options.runnerHeartbeatIntervalMs ?? this.runnerHeartbeatIntervalMs,
+      runnerHeartbeatStaleMs: options.runnerHeartbeatStaleMs ?? this.runnerHeartbeatStaleMs,
+      runnerGroupMaxInstances: options.runnerGroupMaxInstances ?? this.runnerGroupMaxInstances,
+      runnerEnforceMaxInstances: options.runnerEnforceMaxInstances ?? this.runnerEnforceMaxInstances,
+      runnerMetadata: options.runnerMetadata ?? this.runnerMetadata
     });
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AbstractTask,
   Args,
   Box,
   Db,
@@ -5204,13 +6585,15 @@ var TasksManager = class _TasksManager {
   MultiColumnListWithPreviewComponent,
   Params,
   React,
+  S3,
+  SERVICE_TASK_NAMES,
   ScreenBody,
   ScreenContainer,
   ScreenDivider,
   ScreenFooter,
   ScreenRow,
   ScreenTitle,
-  TaskMaster,
+  TaskGetLogs,
   TaskPing,
   TaskSampleProcess,
   TaskShellCommand,
@@ -5225,24 +6608,38 @@ var TasksManager = class _TasksManager {
   buildBreadcrumb,
   buildDetailBreadcrumb,
   buildFooter,
-  dbConnect,
-  dbFindAndConnect,
-  dbInit,
+  convertPattern,
   defaultFileSynopsisFunction,
   defaultTasksRegistry,
   defaultVersionSynopsisFunction,
   enqueueStopTask,
   enqueueTask,
   ensureTaskTables,
+  flushTaskIpcLogs,
   getArgsInstance,
   h,
+  ipcFileLogsTableNameForSourceResource,
   joiEdateType,
   joiStringArrayType,
+  listAliveRunnerHeartbeats,
+  listServicesRegistry,
   listSources,
   listTables,
   load,
+  matchesParsedPattern,
+  memo,
+  mergeAllowedTasksWithServiceTasks,
+  nextTimeMatch,
+  normalizeAllowedTasks,
   organizeFooterMessages,
   queueToTableNames,
+  readTaskIpcLogsSnapshot,
+  registerInServicesRegistry,
+  registerRunnerHeartbeat,
+  resolveAsterisks,
+  resolveIpcFileLogsDir,
+  resolveRanges,
+  resolveSteps,
   runNodeTaskScript,
   runTasksLoop,
   setupContext,
@@ -5252,10 +6649,18 @@ var TasksManager = class _TasksManager {
   showMultiColumnListWithPreviewScreen,
   showScreen,
   showWordGridScreen,
+  taskHistoryInsertFromQueueRow,
+  timeMatcher,
+  touchRunnerHeartbeat,
+  touchServicesRegistry,
+  unregisterRunnerHeartbeat,
+  unregisterServicesRegistry,
+  updateServicesRegistryMetadata,
   updateTaskProgress,
   useCallback,
   useEffect,
   useInput,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,