@nmakarov/cli-toolkit 0.21.0 → 0.23.0

package/dist/index.js

@@ -9,7 +9,7 @@ var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
 
-// src/screen/components.ts
+// src/screen/components.js
 import { createElement as h } from "react";
 import { Box, Text } from "ink";
 function getScreenWidth(maxWidth = null) {
@@ -84,13 +84,12 @@ function ScreenFooter({ lines, textStyle }) {
   );
 }
 var init_components = __esm({
-  "src/screen/components.ts"() {
-    "use strict";
+  "src/screen/components.js"() {
   }
 });
 
-// src/screen/list-components.ts
-import React2, { useState, useEffect, useRef, createElement } from "react";
+// src/screen/list-components.js
+import React, { useState, useEffect, useRef, createElement } from "react";
 import { Box as Box2, Text as Text2 } from "ink";
 function MultiColumnListComponent({ items, ctx, selectedIndexRef }) {
   const [, forceUpdate] = useState({});
@@ -226,11 +225,11 @@ function MultiColumnListWithPreviewComponent({
   const previewRows = [];
   if (typeof previewContent === "string") {
     previewRows.push(h2(ScreenRow, { key: "preview-string", children: h2(Text2, { bold: true }, previewContent) }));
-  } else if (typeof previewContent === "object" && !React2.isValidElement(previewContent) && previewContent !== null) {
+  } else if (typeof previewContent === "object" && !React.isValidElement(previewContent) && previewContent !== null) {
     Object.entries(previewContent).forEach(([key, value], idx) => {
       previewRows.push(h2(ScreenRow, { key: `preview-${key}-${idx}`, children: h2(Text2, {}, `${key}: ${value}`) }));
     });
-  } else if (React2.isValidElement(previewContent)) {
+  } else if (React.isValidElement(previewContent)) {
     previewRows.push(h2(ScreenRow, { key: "preview-element", children: previewContent }));
   }
   return h2(
@@ -243,11 +242,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] = useState({});
   const [sortOrder, setSortOrder] = useState("none");
   const [scrollOffset, setScrollOffset] = useState(0);
   const scrollStateRef = useRef({ scrollOffset: 0, maxHeight: 0, totalItems: 0 });
+  const itemsRef = useRef(items);
+  itemsRef.current = items;
   const defaultGetTitle = (item) => {
     return getTitle ? getTitle(item) : typeof item.value === "string" ? item.value : item.value?.title || item.name;
   };
@@ -261,18 +262,24 @@ function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sor
       return titleA > titleB ? -1 : titleA < titleB ? 1 : 0;
     }
   }) : items;
+  const displayItemsRef = 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 = useRef(onSelectionChange);
+  onSelectionChangeRef.current = onSelectionChange;
   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);
@@ -282,18 +289,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);
@@ -303,8 +303,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({});
@@ -319,9 +318,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") {
@@ -329,7 +328,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;
@@ -467,14 +466,13 @@ function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sor
 }
 var h2;
 var init_list_components = __esm({
-  "src/screen/list-components.ts"() {
-    "use strict";
+  "src/screen/list-components.js"() {
     init_components();
     h2 = createElement;
   }
 });
 
-// src/screen/screens.ts
+// src/screen/screens.js
 import { useState as useState2, createElement as h3 } from "react";
 import { render, useInput, Text as Text3 } from "ink";
 function groupKeyBindings(bindings) {
@@ -552,7 +550,7 @@ async function showScreen(config2) {
     let renderResult = null;
     let initialized = false;
     const Screen = () => {
-      const [updateCounter, setUpdateCounter] = useState2(0);
+      const [, setUpdateCounter] = useState2(0);
       if (!initialized) {
         const defaultBindings = [
           { key: "escape", caption: "go back", action: "back", protected: true, order: 1 },
@@ -671,7 +669,7 @@ async function showScreen(config2) {
           }
         }
         if (matchedBinding && actions[matchedBinding.action]) {
-          const actionResult = actions[matchedBinding.action]({
+          actions[matchedBinding.action]({
             input,
             key,
             binding: matchedBinding
@@ -801,8 +799,7 @@ async function showMultiColumnListWithPreviewScreen(config2) {
 }
 var showMenuScreen, showWordGridScreen;
 var init_screens = __esm({
-  "src/screen/screens.ts"() {
-    "use strict";
+  "src/screen/screens.js"() {
     init_components();
     init_list_components();
     showMenuScreen = showListScreen;
@@ -810,9 +807,9 @@ var init_screens = __esm({
   }
 });
 
-// src/screen/ui-elements.ts
+// src/screen/ui-elements.js
 import { createElement as h4 } from "react";
-import { Box as Box4, Text as Text4 } from "ink";
+import { Box as Box3, Text as Text4 } from "ink";
 function ListItem({
   children,
   isSelected = false,
@@ -822,7 +819,7 @@ function ListItem({
   dimColor = false
 }) {
   return h4(
-    Box4,
+    Box3,
     {},
     h4(Text4, {
       color: isSelected ? backgroundColor || "green" : color,
@@ -837,10 +834,10 @@ function TextBlock({
   color = "white",
   dimmed = false,
   bold = false,
-  maxWidth
+  maxWidth: _maxWidth
 }) {
   return h4(
-    Box4,
+    Box3,
     {},
     h4(Text4, {
       color,
@@ -851,7 +848,7 @@ function TextBlock({
 }
 function Divider({ character = "\u2500", width = 80 }) {
   return h4(
-    Box4,
+    Box3,
     { marginY: 1 },
     h4(Text4, { dimColor: true }, character.repeat(width))
   );
@@ -866,7 +863,7 @@ function GridCell({
   align = "left"
 }) {
   return h4(
-    Box4,
+    Box3,
     { width },
     h4(Text4, {
       color,
@@ -877,25 +874,24 @@ function GridCell({
     }, children)
   );
 }
-function InputField({ prompt, value, onChange, onSubmit }) {
+function InputField({ prompt, value, onChange: _onChange, onSubmit: _onSubmit }) {
   return h4(
-    Box4,
+    Box3,
     { flexDirection: "column" },
     h4(Text4, {}, prompt),
     h4(
-      Box4,
+      Box3,
       { marginTop: 1 },
       h4(Text4, { color: "cyan" }, " > ", value, "_")
     )
   );
 }
 var init_ui_elements = __esm({
-  "src/screen/ui-elements.ts"() {
-    "use strict";
+  "src/screen/ui-elements.js"() {
   }
 });
 
-// src/screen/utils.ts
+// src/screen/utils.js
 function buildBreadcrumb(parts) {
   if (parts.length === 0) return "";
   if (parts.length === 1) return parts[0];
@@ -909,12 +905,11 @@ function buildDetailBreadcrumb(path5, suffix = "") {
   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,
@@ -965,8 +960,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
@@ -1025,9 +1019,9 @@ var init_footer_builder = __esm({
   }
 });
 
-// src/screen/index.ts
-import React5, { useState as useState3, useEffect as useEffect3, useRef as useRef3, useMemo, useCallback, createElement as createElement2 } from "react";
-import { Box as Box5, Text as Text5, useInput as useInput2 } from "ink";
+// src/screen/index.js
+import React2, { useState as useState3, useEffect as useEffect2, useLayoutEffect, useRef as useRef2, useMemo, useCallback, memo, createElement as createElement2 } from "react";
+import { Box as Box4, Text as Text5, useInput as useInput2 } from "ink";
 async function load() {
   if (loadPromise) return loadPromise;
   loadPromise = Promise.all([
@@ -1039,8 +1033,7 @@ async function load() {
 }
 var loadPromise;
 var init_screen = __esm({
-  "src/screen/index.ts"() {
-    "use strict";
+  "src/screen/index.js"() {
     init_screens();
     init_list_components();
     init_components();
@@ -1055,7 +1048,7 @@ var init_screen = __esm({
   }
 });
 
-// src/args/index.ts
+// src/args/index.js
 import { readFileSync, existsSync } from "fs";
 import { resolve, dirname, basename, extname, join, isAbsolute } from "path";
 import { config } from "dotenv";
@@ -1542,10 +1535,10 @@ function getArgsInstance() {
   return instance;
 }
 
-// src/params/index.ts
+// src/params/index.js
 import Joi from "joi";
 
-// src/errors.ts
+// src/errors.js
 var FrameworkError = class extends Error {
   constructor(message) {
     super(message);
@@ -1565,7 +1558,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);
@@ -1658,7 +1651,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 [];
   }
@@ -1684,7 +1677,7 @@ var joiStringArrayType = (type) => (value, helpers) => {
   return arr;
 };
 
-// src/params/index.ts
+// src/params/index.js
 var Params = class _Params {
   context;
   // Partial context during initialization
@@ -1944,7 +1937,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;
     }
@@ -2063,14 +2056,14 @@ var Params = class _Params {
   }
 };
 
-// src/screen.ts
+// src/index.js
 init_screen();
 
-// src/filedatabase/index.ts
+// src/filedatabase/index.js
 import fs3 from "fs";
 import path3 from "path";
 
-// src/utils/os-utils.ts
+// src/utils/os-utils.js
 import fs from "fs";
 import path from "path";
 import { execSync } from "child_process";
@@ -2099,7 +2092,7 @@ function getFreeDiskSpace(targetPath) {
   }
 }
 
-// src/utils/fs-utils.ts
+// src/utils/fs-utils.js
 import fs2 from "fs";
 import path2 from "path";
 async function ensurePath(...pathParts) {
@@ -2123,7 +2116,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;
@@ -2132,7 +2125,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)) {
@@ -2142,7 +2135,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";
@@ -2174,7 +2167,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 };
@@ -2242,7 +2235,7 @@ function defaultVersionSynopsisFunction(metadata) {
   return result;
 }
 
-// src/filedatabase/index.ts
+// src/filedatabase/index.js
 var FileDatabase = class _FileDatabase {
   basePath;
   namespace;
@@ -2328,7 +2321,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("/"));
     }
@@ -2821,14 +2814,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);
@@ -2938,7 +2934,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) {
@@ -3253,22 +3249,57 @@ function listSources(basePath) {
   }
 }
 
-// src/db/index.ts
+// src/db/index.js
 import knex from "knex";
+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,
@@ -3281,25 +3312,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",
@@ -3312,26 +3341,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;
         }
@@ -3339,9 +3368,6 @@ var Db = class {
       }
     });
   }
-  /**
-   * Detect database client type from connection string
-   */
   detectClient(connectionString) {
     if (connectionString.match(/^postgresql/)) {
       return "pg";
@@ -3351,9 +3377,6 @@ var Db = class {
     }
     return null;
   }
-  /**
-   * Connect to the database
-   */
   async connect() {
     if (this.isConnected && this.knexInstance) {
       this.logger.warn?.("[Db] Already connected");
@@ -3362,14 +3385,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 = knex({
         client,
@@ -3385,7 +3407,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;
@@ -3394,9 +3418,6 @@ var Db = class {
       throw new ParamError(`Db: Connection failed - ${errorMsg}`);
     }
   }
-  /**
-   * Disconnect from the database
-   */
   async disconnect() {
     if (!this.knexInstance) {
       return;
@@ -3406,16 +3427,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 || [];
@@ -3440,9 +3460,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];
         }
@@ -3451,28 +3473,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.");
@@ -3488,9 +3507,6 @@ var Db = class {
       throw new ParamError(`Db: Connection test failed - ${errorMsg}`);
     }
   }
-  /**
-   * Attach query profiler to log all queries
-   */
   attachProfiler() {
     if (!this.knexInstance) {
       return;
@@ -3500,7 +3516,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 = {
@@ -3515,15 +3531,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.");
@@ -3535,65 +3545,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) {
@@ -3603,52 +3576,266 @@ 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
+import {
+  S3Client,
+  HeadBucketCommand,
+  HeadObjectCommand,
+  GetObjectCommand,
+  PutObjectCommand,
+  DeleteObjectCommand,
+  CopyObjectCommand,
+  ListObjectsV2Command,
+  PutObjectTaggingCommand,
+  GetObjectTaggingCommand
+} from "@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.getAll(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 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 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 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 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 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 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 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 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 PutObjectTaggingCommand({
+      Bucket: this.bucketName,
+      Key: key,
+      Tagging: { TagSet: this._tagsToTagSet(tags) }
+    }));
+  }
+  async getObjectTagging(key) {
+    const out = await this.client.send(new 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
 import chalk from "chalk";
 import util from "util";
 
-// src/logger/transports.ts
+// src/logger/transports.js
 var ConsoleTransport = class {
   write(payload) {
     console.info(payload);
@@ -3668,7 +3855,7 @@ var ParentProcessTransport = class {
   }
 };
 
-// src/logger/index.ts
+// src/logger/index.js
 var ALL_LEVELS = [
   "silly",
   "debug",
@@ -3741,6 +3928,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 = {
@@ -3754,7 +3942,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;
@@ -3950,9 +4138,9 @@ var Logger = class _Logger {
   }
 };
 
-// src/init/index.ts
+// src/init/index.js
 import { EventEmitter } from "events";
-function extractComponentOptions(opts, componentName) {
+function extractComponentOptions(opts, _componentName) {
   const reservedKeys = ["overrides", "defaults", "modules"];
   const componentOptions = {};
   for (const [key, value] of Object.entries(opts)) {
@@ -3997,7 +4185,10 @@ function setupContext(opts = {}) {
   return setup(opts);
 }
 
-// src/utils/core-utils.ts
+// src/tasks/index.js
+import os3 from "os";
+
+// src/utils/core-utils.js
 function sleepMs(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
@@ -4006,14 +4197,82 @@ function toJsonColumn(value) {
   return JSON.stringify(value);
 }
 
-// src/tasks/servicesRegistry.ts
-import { randomUUID as randomUUID2 } from "crypto";
-import { mkdir, readFile, writeFile } from "fs/promises";
+// src/tasks/servicesRegistry.js
 import os from "os";
-import path4 from "path";
 
-// src/tasks/taskUtils.ts
+// src/tasks/taskUtils.js
 import { randomUUID } from "crypto";
+
+// src/tasks/time-matcher.js
+var RANGES = ["0-59", "0-59", "0-23", "1-31", "1-12", "0-6"];
+function resolveAsterisks(field, range) {
+  return field.includes("*") ? field.replace("*", range) : field;
+}
+function resolveRanges(field) {
+  const regex = /(\d+)-(\d+)/;
+  let current = field;
+  while (true) {
+    const match = regex.exec(current);
+    if (!match) break;
+    const raw = match[0];
+    let first = Number(match[1]);
+    let last = Number(match[2]);
+    if (last < first) {
+      [first, last] = [last, first];
+    }
+    const values = [];
+    for (let i = first; i <= last; i += 1) {
+      values.push(i);
+    }
+    current = current.replace(raw, values.join(","));
+  }
+  return current;
+}
+function resolveSteps(field) {
+  const match = /^(.+)\/(\d+)$/.exec(field);
+  if (!match) return field;
+  const base = match[1];
+  const step = Number(match[2]);
+  if (!Number.isFinite(step) || step <= 0) return field;
+  return base.split(",").map((v) => Number(v)).filter((v) => Number.isFinite(v) && v % step === 0).join(",");
+}
+function convertPattern(pattern) {
+  const parts = pattern.trim().split(/\s+/);
+  if (parts.length !== 6) {
+    throw new Error(`Invalid schedule "${pattern}". Expected 6 fields: sec min hour day month weekday`);
+  }
+  return parts.map((field, idx) => resolveAsterisks(field, RANGES[idx])).map((field) => resolveRanges(field)).map((field) => resolveSteps(field));
+}
+function fieldMatches(field, value) {
+  const allowed = field.split(",").map((v) => Number(v));
+  return allowed.includes(value);
+}
+function matchesParsedPattern(parsed, date) {
+  return fieldMatches(parsed[0], date.getSeconds()) && fieldMatches(parsed[1], date.getMinutes()) && fieldMatches(parsed[2], date.getHours()) && fieldMatches(parsed[3], date.getDate()) && fieldMatches(parsed[4], date.getMonth() + 1) && fieldMatches(parsed[5], date.getDay());
+}
+function timeMatcher(pattern, date = /* @__PURE__ */ new Date()) {
+  const parsed = convertPattern(pattern);
+  return matchesParsedPattern(parsed, date);
+}
+var MS_PER_SECOND = 1e3;
+var DEFAULT_SEARCH_HORIZON_MS = 10 * 365 * 24 * 60 * 60 * MS_PER_SECOND;
+function nextTimeMatch(pattern, from = /* @__PURE__ */ new Date(), maxSearchMs = DEFAULT_SEARCH_HORIZON_MS) {
+  const parsed = convertPattern(pattern);
+  let t = Math.ceil((from.getTime() + 1) / MS_PER_SECOND) * MS_PER_SECOND;
+  const end = t + maxSearchMs;
+  while (t <= end) {
+    const date = new Date(t);
+    if (matchesParsedPattern(parsed, date)) {
+      return date;
+    }
+    t += MS_PER_SECOND;
+  }
+  throw new Error(
+    `nextTimeMatch: no match for "${pattern}" within ${maxSearchMs}ms after ${from.toISOString()}`
+  );
+}
+
+// src/tasks/taskUtils.js
 function getDb(context) {
   const db = context.db;
   if (!db) {
@@ -4021,113 +4280,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: queue,
-    historyTable: `${queue}_history`
+    tasksTable: queueName,
+    historyTable: `${queueName}_history`,
+    registryTable: `${queueName}_services_registry`
   };
 }
-function servicesRegistryTable(queue) {
-  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(queue)) {
-    throw new Error(`Invalid queue name "${queue}". Use letters, numbers, underscore only.`);
-  }
-  return `${queue}_services_registry`;
+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 {
+    ...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`);
+      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 registryTable = servicesRegistryTable(queue);
-  const needsRegistry = !await db.tableExists(registryTable);
   if (needsRegistry) {
     await db.schema.createTable(registryTable, (t) => {
       t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
-      t.uuid("instance_id").notNullable().unique();
-      t.text("queue").notNullable();
+      t.text("queue_name").notNullable();
       t.text("service_group").notNullable();
+      t.integer("instance_number").notNullable().defaultTo(1);
       t.text("service_name").notNullable();
-      t.text("target").notNullable();
-      t.text("hostname");
+      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", "service_name"], `${registryTable}_queue_service_name_uniq`);
-      t.index(["queue", "service_group", "last_seen_at"], `${registryTable}_queue_group_seen_idx`);
-      t.index(["queue", "last_seen_at"], `${registryTable}_queue_seen_idx`);
+      t.unique(["queue_name", "service_name"], `${registryTable}_queue_name_service_name_uniq`);
+      t.index(["queue_name", "service_group", "last_seen_at"], `${registryTable}_queue_group_seen_idx`);
+      t.index(["queue_name", "last_seen_at"], `${registryTable}_queue_seen_idx`);
     });
   }
 }
 async function enqueueTask(context, options) {
   const db = getDb(context);
-  const queue = options.queue ?? "tasks";
-  const { tasksTable } = queueToTableNames(queue);
+  const queueName = options.queueName ?? "tasks";
+  const { tasksTable } = queueToTableNames(queueName);
   const id = randomUUID();
+  const name = options.name ?? options.task;
+  if (!name) {
+    throw new Error("enqueueTask: name (or task) is required");
+  }
+  const schedule = options.schedule?.trim() ? options.schedule : null;
+  let nextRunAt = null;
+  if (options.nextRunAt !== void 0) {
+    nextRunAt = options.nextRunAt == null ? null : new Date(options.nextRunAt);
+  } else if (schedule) {
+    nextRunAt = nextTimeMatch(schedule, /* @__PURE__ */ new Date());
+  }
   await db(tasksTable).insert({
     id,
-    target: options.target,
-    task: options.task,
+    name,
     params: toJsonColumn(options.params ?? null),
     opid: options.opid ?? null,
-    priority: options.priority ?? 0,
-    schedule: options.schedule ?? null
+    priority: options.priority ?? 50,
+    schedule,
+    next_run_at: nextRunAt,
+    service_group: options.serviceGroup ?? null,
+    instance_number: options.instanceNumber ?? null,
+    service_name: options.serviceName ?? null,
+    server_name: options.serverName ?? null,
+    status: "idle",
+    status_changed_at: db.fn.now()
   });
   return id;
 }
@@ -4138,7 +4401,7 @@ async function updateTaskProgress(context, tasksTable, taskId, progress) {
   });
 }
 
-// src/tasks/servicesRegistry.ts
+// src/tasks/servicesRegistry.js
 function getDb2(context) {
   const db = context.db;
   if (!db) {
@@ -4152,7 +4415,7 @@ function parseMetadataColumn(value) {
   if (typeof value === "string") {
     try {
       const p = JSON.parse(value);
-      return p && typeof p === "object" && !Array.isArray(p) ? p : {};
+      return p && typeof p === "object" && !Array.isArray(value) ? p : {};
     } catch {
       return {};
     }
@@ -4162,6 +4425,7 @@ function parseMetadataColumn(value) {
 var DEFAULT_GROUP_MAX_INSTANCES = {
   intake: 1,
   harvest: 1,
+  harvester: 0,
   loader: 0,
   photos: 0,
   photosprocessor: 0,
@@ -4171,25 +4435,6 @@ function sanitizeNamePart(raw) {
   const s = String(raw || "").trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
   return s.slice(0, 80) || "runner";
 }
-function identityFilePath(identityDir, queue, serviceGroup) {
-  const safeQ = sanitizeNamePart(queue);
-  const safeG = sanitizeNamePart(serviceGroup);
-  return path4.join(identityDir, `${safeQ}_${safeG}.json`);
-}
-async function readIdentityFile(filePath) {
-  try {
-    const text = await readFile(filePath, "utf8");
-    const parsed = JSON.parse(text);
-    return parsed && typeof parsed === "object" ? parsed : {};
-  } catch {
-    return {};
-  }
-}
-async function writeIdentityFile(filePath, data) {
-  await mkdir(path4.dirname(filePath), { recursive: true });
-  await writeFile(filePath, `${JSON.stringify(data, null, 2)}
-`, "utf8");
-}
 function resolveMaxInstances(serviceGroup, override) {
   if (override !== void 0 && Number.isFinite(override)) {
     return Math.max(0, Math.floor(Number(override)));
@@ -4197,179 +4442,190 @@ function resolveMaxInstances(serviceGroup, override) {
   const g = serviceGroup.trim().toLowerCase();
   return DEFAULT_GROUP_MAX_INSTANCES[g] ?? 0;
 }
-async function countAliveInGroup(db, registryTable, queue, serviceGroup, staleMs, excludeInstanceId) {
+async function countAliveInGroup(db, registryTable, queueName, serviceGroup, staleMs, excludeRowId) {
   const cutoff = new Date(Date.now() - staleMs);
-  let q = db(registryTable).where({ queue, service_group: serviceGroup }).where("last_seen_at", ">", cutoff);
-  if (excludeInstanceId) {
-    q = q.whereNot("instance_id", excludeInstanceId);
+  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 = servicesRegistryTable(options.queue);
+  const registryTable = queueToTableNames(options.queueName).registryTable;
   const serviceGroup = options.serviceGroup.trim();
   if (!serviceGroup) {
     throw new Error("registerInServicesRegistry: serviceGroup is required");
   }
-  const identityPath = identityFilePath(options.identityDir, options.queue, serviceGroup);
-  let identity = await readIdentityFile(identityPath);
-  let instanceId = typeof identity.instanceId === "string" && identity.instanceId.trim() ? identity.instanceId.trim() : randomUUID2();
-  identity.instanceId = instanceId;
-  await writeIdentityFile(identityPath, identity);
-  const hostname = os.hostname();
+  const serverName = os.hostname();
   const pid = typeof process.pid === "number" ? process.pid : null;
-  const meta = toJsonColumn(options.metadata ?? null);
-  const existing = await db(registryTable).where({ instance_id: instanceId }).first();
-  if (existing) {
-    await db(registryTable).where({ instance_id: instanceId }).update({
-      target: options.target,
-      hostname,
-      pid,
-      metadata: meta,
-      last_seen_at: db.fn.now()
-    });
-    const serviceName = String(existing.service_name);
-    identity.serviceName = serviceName;
-    await writeIdentityFile(identityPath, identity);
-    const reg = {
-      instanceId,
-      serviceName,
-      serviceGroup,
-      queue: options.queue,
-      target: options.target,
-      rowId: String(existing.id)
-    };
-    context.servicesRegistry = reg;
-    context.runnerHeartbeat = reg;
-    context.logger.info?.(
-      `[services-registry] resumed instance_id=${instanceId} name=${serviceName} group=${serviceGroup} queue=${options.queue}`
-    );
-    return {
-      instanceId,
-      serviceName,
-      serviceGroup,
-      queue: options.queue,
-      target: options.target,
-      rowId: String(existing.id),
-      registryTable
-    };
-  }
+  const meta = buildMetadata(options);
+  const groupBase = sanitizeNamePart(serviceGroup);
+  const hostBase = sanitizeNamePart(serverName);
   const maxAllowed = resolveMaxInstances(serviceGroup, options.groupMaxInstances);
-  const aliveOthers = await countAliveInGroup(
-    db,
-    registryTable,
-    options.queue,
-    serviceGroup,
-    options.staleMs,
-    instanceId
-  );
-  if (maxAllowed > 0 && aliveOthers >= maxAllowed) {
-    const msg = `[services-registry] group limit reached for "${serviceGroup}": ${aliveOthers} alive (max ${maxAllowed}, queue=${options.queue}).`;
+  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 explicitName = options.serviceName?.trim();
-  const fromFile = typeof identity.serviceName === "string" ? identity.serviceName.trim() : "";
-  const hostBase = sanitizeNamePart(hostname);
-  const groupBase = sanitizeNamePart(serviceGroup);
-  const baseCandidates = [];
-  if (explicitName) baseCandidates.push(sanitizeNamePart(explicitName));
-  if (fromFile) baseCandidates.push(sanitizeNamePart(fromFile));
-  baseCandidates.push(`${groupBase}-${hostBase}`);
-  baseCandidates.push(groupBase);
-  function* eachServiceNameCandidate(bases) {
-    const seen = /* @__PURE__ */ new Set();
-    for (const rawBase of bases) {
-      const base = sanitizeNamePart(rawBase);
-      if (!base) continue;
-      const seq = [base];
-      for (let n = 2; n <= 500; n++) seq.push(`${base}-${n}`);
-      for (const c of seq) {
-        if (seen.has(c)) continue;
-        seen.add(c);
-        yield c;
+  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;
     }
-  }
-  let inserted;
-  for (const candidate of eachServiceNameCandidate(baseCandidates)) {
     try {
       const rows = await db(registryTable).insert({
-        instance_id: instanceId,
-        queue: options.queue,
+        queue_name: options.queueName,
         service_group: serviceGroup,
-        service_name: candidate,
-        target: options.target,
-        hostname,
+        instance_number: instanceNumber,
+        service_name: serviceNameRaw,
+        server_name: serverName,
         pid,
         metadata: meta,
-        last_seen_at: db.fn.now()
+        last_seen_at: db.fn.now(),
+        created_at: db.fn.now()
       }).returning(["id", "service_name"]);
       const row = Array.isArray(rows) ? rows[0] : rows;
-      if (row) {
-        inserted = { id: String(row.id), service_name: String(row.service_name) };
-        break;
+      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})`);
     }
   }
-  if (!inserted) {
-    throw new Error(
-      `[services-registry] could not allocate a unique service_name for group=${serviceGroup} queue=${options.queue} (too many collisions).`
-    );
-  }
-  identity.serviceName = inserted.service_name;
-  await writeIdentityFile(identityPath, identity);
-  const regNew = {
-    instanceId,
-    serviceName: inserted.service_name,
-    serviceGroup,
-    queue: options.queue,
-    target: options.target,
-    rowId: inserted.id
-  };
-  context.servicesRegistry = regNew;
-  context.runnerHeartbeat = regNew;
-  context.logger.info?.(
-    `[services-registry] registered instance_id=${instanceId} name=${inserted.service_name} group=${serviceGroup} queue=${options.queue} target=${options.target}`
+  throw new Error(
+    `[services-registry] could not allocate a registry row for group=${serviceGroup} queue=${options.queueName} after ${MAX_ATTEMPTS} attempts`
   );
-  return {
-    instanceId,
-    serviceName: inserted.service_name,
-    serviceGroup,
-    queue: options.queue,
-    target: options.target,
-    rowId: inserted.id,
-    registryTable
-  };
 }
 async function touchServicesRegistry(context, registration) {
   const db = getDb2(context);
-  const hostname = os.hostname();
+  const serverName = os.hostname();
   const pid = typeof process.pid === "number" ? process.pid : null;
-  await db(registration.registryTable).where({ instance_id: registration.instanceId }).update({
+  await db(registration.registryTable).where({ id: registration.rowId }).update({
     last_seen_at: db.fn.now(),
-    hostname,
+    server_name: serverName,
     pid
   });
 }
 async function updateServicesRegistryMetadata(context, registration, patch) {
   const db = getDb2(context);
-  const row = await db(registration.registryTable).where({ instance_id: registration.instanceId }).first();
+  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({ instance_id: registration.instanceId }).update({
+  await db(registration.registryTable).where({ id: registration.rowId }).update({
     metadata: toJsonColumn(merged),
     last_seen_at: db.fn.now()
   });
@@ -4377,14 +4633,14 @@ async function updateServicesRegistryMetadata(context, registration, patch) {
 }
 async function unregisterServicesRegistry(context, registration) {
   const db = getDb2(context);
-  await db(registration.registryTable).where({ instance_id: registration.instanceId }).delete();
-  context.logger.info?.(`[services-registry] unregistered name=${registration.serviceName} instance_id=${registration.instanceId}`);
+  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 = { queue: "tasks" }) {
+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 = servicesRegistryTable(options.queue);
+  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() });
@@ -4392,7 +4648,8 @@ async function listServicesRegistry(context, options = { queue: "tasks" }) {
   return await q;
 }
 
-// src/tasks/taskLogs.ts
+// src/tasks/taskLogs.js
+import path4 from "path";
 function getLogsState(context) {
   const holder = context;
   if (holder.__tasksLogsState) return holder.__tasksLogsState;
@@ -4445,33 +4702,135 @@ function getLogsState(context) {
   holder.__tasksLogsState = state;
   return state;
 }
-function isErrorPayload(payload) {
-  if (!payload) return false;
-  if (typeof payload === "object") {
-    const level = typeof payload.level === "string" ? payload.level.toLowerCase() : "";
-    if (level === "error" || level === "fatal") return true;
-    if (typeof payload.message === "string" && /\berror\b/i.test(payload.message)) return true;
-    return false;
-  }
-  if (typeof payload === "string") {
-    return /\berror\b/i.test(payload);
-  }
-  return false;
+function ipcLogTargetKey(target) {
+  const bp = target.basePath ?? "";
+  const ns = target.namespace ?? "";
+  return `${bp}::${ns}::${target.tableName}`;
 }
-function buildLogRecord(task, payload) {
+function ipcFileLogsTableNameForSourceResource(source, resource) {
+  const seg = (s) => {
+    const t = String(s).trim().replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+|_+$/g, "");
+    return t.length ? t : "x";
+  };
+  return `${seg(source)}/${seg(resource)}`;
+}
+async function readTaskIpcLogsSnapshot(context, options) {
+  const holder = context;
+  const basePath = holder.params?.get?.("tasksLogsBasePath") ?? "./data";
+  const namespace = holder.params?.get?.("tasksLogsNamespace") ?? "tasks-logs";
+  const tableName = ipcFileLogsTableNameForSourceResource(options.source, options.resource);
+  const tail = Math.max(1, Math.min(1e4, Number(options.tail) > 0 ? Number(options.tail) : 100));
+  const fd = new FileDatabase({
+    basePath,
+    namespace,
+    tableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: 30,
+    pageSize: 2e3,
+    logger: holder.logger
+  });
+  const versions = await fd.getVersions();
+  if (versions.length === 0) {
+    return { records: [], latestTs: null };
+  }
+  const latest = versions[versions.length - 1];
+  const raw = await fd.read({ version: latest });
+  const arr = Array.isArray(raw) ? raw : [];
+  let filtered = arr;
+  if (options.afterTs && String(options.afterTs).trim()) {
+    const cut = String(options.afterTs).trim();
+    filtered = arr.filter((r) => r && typeof r.ts === "string" && String(r.ts) > cut);
+  }
+  let latestTs = null;
+  for (const r of filtered) {
+    const ts = typeof r?.ts === "string" ? String(r.ts) : null;
+    if (ts && (!latestTs || ts > latestTs)) latestTs = ts;
+  }
+  const incremental = !!(options.afterTs && String(options.afterTs).trim());
+  const maxReturn = incremental ? 1e4 : tail;
+  const sliced = filtered.length > maxReturn ? filtered.slice(-maxReturn) : filtered;
+  return { records: sliced, latestTs };
+}
+function resolveIpcFileLogsDir(context, target) {
+  const holder = context;
+  const basePath = target.basePath ?? (holder.params?.get?.("tasksLogsBasePath") || "./data");
+  const namespace = target.namespace ?? (holder.params?.get?.("tasksLogsNamespace") || "tasks-logs");
+  const segments = target.tableName.split("/").filter(Boolean);
+  return path4.resolve(basePath, namespace, ...segments);
+}
+function getLogsStateForTarget(context, target) {
+  const holder = context;
+  const enabledRaw = holder.params?.get?.("tasksLogsEnabled");
+  const enabled = enabledRaw === void 0 ? true : !!enabledRaw;
+  if (!enabled) return null;
+  if (!holder.__tasksLogsTargetStates) holder.__tasksLogsTargetStates = /* @__PURE__ */ new Map();
+  const map = holder.__tasksLogsTargetStates;
+  const key = ipcLogTargetKey(target);
+  if (map.has(key)) return map.get(key);
+  const basePath = target.basePath ?? (holder.params?.get?.("tasksLogsBasePath") || "./data");
+  const namespace = target.namespace ?? (holder.params?.get?.("tasksLogsNamespace") || "tasks-logs");
+  const maxVersionsRaw = Number(holder.params?.get?.("tasksLogsMaxVersions"));
+  const pageSizeRaw = Number(holder.params?.get?.("tasksLogsPageSize"));
+  const db = new FileDatabase({
+    basePath,
+    namespace,
+    tableName: target.tableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: Number.isFinite(maxVersionsRaw) && maxVersionsRaw > 0 ? maxVersionsRaw : 20,
+    pageSize: Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 2e3,
+    logger: holder.logger
+  });
+  const state = {
+    db,
+    errorDb: null,
+    queue: Promise.resolve(),
+    initialized: false,
+    errorInitialized: false
+  };
+  map.set(key, state);
+  return state;
+}
+function isErrorPayload(payload) {
+  if (!payload) return false;
+  if (typeof payload === "object") {
+    const level = typeof payload.level === "string" ? payload.level.toLowerCase() : "";
+    if (level === "error" || level === "fatal") return true;
+    if (typeof payload.message === "string" && /\berror\b/i.test(payload.message)) return true;
+    return false;
+  }
+  if (typeof payload === "string") {
+    return /\berror\b/i.test(payload);
+  }
+  return false;
+}
+function buildLogRecord(task, payload) {
   const params = task.params && typeof task.params === "object" ? task.params : {};
   return {
     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);
@@ -4488,84 +4847,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;
@@ -4573,6 +5141,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;
@@ -4654,7 +5230,7 @@ var TaskSampleProcess = class extends TaskMaster {
   }
 };
 
-// src/tasks/coreTasks/TaskShellCommand.ts
+// src/tasks/coreTasks/TaskShellCommand.js
 import { spawn } from "child_process";
 function runShellCommand(command, cwd) {
   return new Promise((resolve2, reject) => {
@@ -4684,7 +5260,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;
@@ -4733,7 +5329,7 @@ var TaskShellCommand = class extends TaskMaster {
   }
 };
 
-// src/tasks/coreTasks/TaskSystemInfo.ts
+// src/tasks/coreTasks/TaskSystemInfo.js
 import os2 from "os";
 import fs4 from "fs/promises";
 function toGb(valueBytes) {
@@ -4753,7 +5349,16 @@ 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 = os2.totalmem();
@@ -4805,8 +5410,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;
@@ -4837,8 +5465,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})`);
@@ -4853,172 +5519,396 @@ var TaskStopRunner = class extends TaskMaster {
   }
 };
 
-// src/tasks/TasksRegistry.ts
+// src/tasks/coreTasks/TaskGetLogs.js
+var TaskGetLogs = class extends AbstractTask {
+  /**
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<{ source: string, resource: string, tail: number, afterTs?: string }>}
+   */
+  static async resolveCustomParams(context, overrides = {}) {
+    const merged = AbstractTask._mergeTypedParams(context, "task-get-logs", {
+      source: "string",
+      resource: "string",
+      tail: "number default 100",
+      afterTs: "string"
+    }, overrides);
+    const source = typeof merged.source === "string" ? merged.source.trim() : "";
+    const resource = typeof merged.resource === "string" ? merged.resource.trim() : "";
+    if (!source) throw new ParamError('getLogs: param "source" is required');
+    if (!resource) throw new ParamError('getLogs: param "resource" is required');
+    let tail = Number(merged.tail);
+    if (!Number.isFinite(tail) || tail < 1) tail = 100;
+    tail = Math.min(1e4, Math.max(1, Math.floor(tail)));
+    const out = { source, resource, tail };
+    if (typeof merged.afterTs === "string" && merged.afterTs.trim()) {
+      out.afterTs = merged.afterTs.trim();
+    }
+    return out;
+  }
+  /**
+   * @param {unknown} _reportProgress Unused (single-shot read, no progress events).
+   * @returns {Promise<{ success: boolean, results: unknown }>}
+   */
+  async run(_reportProgress) {
+    const p = this.task.params ?? {};
+    const source = String(p.source ?? "").trim();
+    const resource = String(p.resource ?? "").trim();
+    const tail = Math.max(1, Math.min(1e4, Number(p.tail) > 0 ? Number(p.tail) : 100));
+    const afterTs = p.afterTs != null && String(p.afterTs).trim() ? String(p.afterTs).trim() : null;
+    if (!source || !resource) {
+      return {
+        success: false,
+        results: { error: 'getLogs requires params "source" and "resource"' }
+      };
+    }
+    try {
+      const { records, latestTs } = await readTaskIpcLogsSnapshot(this.context, {
+        source,
+        resource,
+        tail,
+        afterTs
+      });
+      return {
+        success: true,
+        results: { records, latestTs, source, resource }
+      };
+    } catch (e) {
+      return {
+        success: false,
+        results: { error: e?.message ?? String(e) }
+      };
+    }
+  }
+};
+
+// src/tasks/TasksRegistry.js
 var TasksRegistry = class _TasksRegistry {
-  map = {};
+  /**
+   * @param {Record<string, Function>} [initial] Optional seed entries to copy in.
+   */
   constructor(initial) {
+    this.map = {};
     if (initial) {
       this.addMany(initial);
     }
   }
+  /**
+   * Build a registry pre-populated with every core task plus legacy aliases.
+   * Prefer this over `new TasksRegistry()` for anything that wants `ping`/`stop`/etc.
+   *
+   * @returns {TasksRegistry}
+   */
   static withCoreTasks() {
-    return new _TasksRegistry().add("ping", TaskPing).add("sampleProcess", TaskSampleProcess).add("shellCommand", TaskShellCommand).add("systemInfo", TaskSystemInfo).add("taskSumAB", TaskSumAB).add("stopRunner", TaskStopRunner).add("stop", TaskStopRunner);
+    return new _TasksRegistry().add("ping", TaskPing).add("sampleProcess", TaskSampleProcess).add("shellCommand", TaskShellCommand).add("systemInfo", TaskSystemInfo).add("info", TaskSystemInfo).add("taskSumAB", TaskSumAB).add("stopRunner", TaskStopRunner).add("stop", TaskStopRunner).add("getLogs", TaskGetLogs);
   }
+  /**
+   * Register a single task class under a name. Overwrites any previous entry.
+   *
+   * @param {string} taskName
+   * @param {Function} taskClass Subclass of `AbstractTask`.
+   * @returns {this}
+   */
   add(taskName, taskClass) {
     this.map[taskName] = taskClass;
     return this;
   }
+  /**
+   * Bulk-register a name → class map. Later calls override earlier ones.
+   *
+   * @param {Record<string, Function>} entries
+   * @returns {this}
+   */
   addMany(entries) {
     for (const [name, klass] of Object.entries(entries)) {
       this.add(name, klass);
     }
     return this;
   }
+  /**
+   * Look up a task class by name. Returns `undefined` when the name is unknown;
+   * the runner treats that as "some other worker may handle this" and skips.
+   *
+   * @param {string} taskName
+   * @returns {Function | undefined}
+   */
   get(taskName) {
     return this.map[taskName];
   }
+  /**
+   * Strict variant of {@link get}: throws {@link ParamError} (with the list
+   * of supported names) when `taskName` is unknown. Use from enqueuer code
+   * paths where an unknown name is a hard CLI/programmer error.
+   *
+   * @param {string} taskName
+   * @returns {Function}
+   */
+  requireClass(taskName) {
+    const TaskClass = taskName ? this.map[taskName] : void 0;
+    if (!TaskClass) {
+      const supported = this.listSupportedTasks().join(", ") || "(none)";
+      throw new ParamError(
+        `Unknown task "${taskName ?? ""}". Supported on this registry: ${supported}`
+      );
+    }
+    return TaskClass;
+  }
+  /**
+   * Dispatcher used by `send-task` / programmatic enqueuers: pick `name`
+   * from `overrides` or `context.params`, look up the class, and delegate
+   * to its static {@link AbstractTask.resolveParams} with `name` seeded into
+   * the overrides. The returned object is shaped for {@link enqueueTask}.
+   *
+   * Validation failures (unknown task, missing required custom params, etc.)
+   * surface as {@link ParamError} so the caller aborts cleanly before any
+   * row is inserted.
+   *
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<object>}
+   */
+  async resolveTaskParams(context, overrides = {}) {
+    const overrideName = typeof overrides.name === "string" ? overrides.name.trim() : overrides.name;
+    const fromCli = context.params.get("name", "string");
+    const cliName = typeof fromCli === "string" ? fromCli.trim() : fromCli;
+    const name = overrideName || cliName;
+    if (!name) {
+      throw new ParamError("Task --name is required (e.g. ping, stop, dummyHarvest)");
+    }
+    const TaskClass = this.requireClass(name);
+    return TaskClass.resolveParams(context, { ...overrides, name });
+  }
+  /**
+   * Names of every registered task, sorted alphabetically (useful for CLI output
+   * and allowlist sanity checks).
+   *
+   * @returns {string[]}
+   */
   listSupportedTasks() {
     return Object.keys(this.map).sort();
   }
+  /**
+   * Shallow copy of the internal map, for handing to `addMany` on another registry
+   * or for serialization.
+   *
+   * @returns {Record<string, Function>}
+   */
   toObject() {
     return { ...this.map };
   }
 };
 
-// src/tasks/taskScriptRunner.ts
+// src/tasks/serviceTaskAllowlist.js
+var SERVICE_TASK_NAMES = [
+  "ping",
+  "stop",
+  "stopRunner",
+  "shellCommand",
+  "systemInfo",
+  "info",
+  "getLogs"
+];
+function normalizeAllowedTasks(value) {
+  if (!value) return void 0;
+  if (Array.isArray(value)) {
+    const out2 = value.map((v) => String(v).trim()).filter(Boolean);
+    return out2.length ? out2 : void 0;
+  }
+  const out = String(value).split(",").map((v) => v.trim()).filter(Boolean);
+  return out.length ? out : void 0;
+}
+function mergeAllowedTasksWithServiceTasks(names) {
+  const set = /* @__PURE__ */ new Set([...SERVICE_TASK_NAMES, ...names ?? []]);
+  return Array.from(set).sort();
+}
+
+// src/tasks/taskScriptRunner.js
 import { spawn as spawn2 } from "child_process";
+var MAX_PROGRESS_TEXT_LEN = 4e3;
 function toCliArgs(args = []) {
   return args.filter((a) => typeof a === "string" && a.length > 0);
 }
 function formatChildLogPrefix(task) {
-  return `${task.task}:${task.id.slice(0, 8)}${task.opid ? `:${task.opid}` : ""}`;
+  return `${task.name}:${task.id.slice(0, 8)}${task.opid ? `:${task.opid}` : ""}`;
 }
-async function runNodeTaskScript(context, options) {
-  const cliArgs = toCliArgs(["--route=ipc", "--mode=json", ...options.args || []]);
+function isProgressPayload(payload) {
+  if (!payload || typeof payload !== "object") return false;
+  if (payload.level !== "progress") return false;
+  const count = Number(payload.count);
+  const total = Number(payload.total);
+  return Number.isFinite(count) && Number.isFinite(total) && total > 0;
+}
+function formatProgressText(payload, fallbackPrefix) {
+  const pfx = payload.prefix ? `${payload.prefix} ` : fallbackPrefix ? `${fallbackPrefix} ` : "";
+  const label = typeof payload.message === "string" && payload.message ? `${payload.message} ` : "";
+  return `${pfx}${label}${payload.count}/${payload.total}`;
+}
+function forwardChildLogToParent(context, prefix, message) {
+  if (!message || typeof message !== "object") return;
+  const text = typeof message.message === "string" ? message.message : null;
+  if (!text) return;
+  const level = typeof message.level === "string" ? message.level.toLowerCase() : "";
+  const line = `[child:${prefix}] ${text}`;
+  const logger = context.logger;
+  switch (level) {
+    case "error":
+    case "fatal":
+      logger.error?.(line);
+      return;
+    case "warn":
+    case "warning":
+      logger.warn?.(line);
+      return;
+    case "debug":
+      logger.debug?.(line);
+      return;
+    case "info":
+    default:
+      logger.info?.(line);
+  }
+}
+function buildNodeArgs(scriptPath, cliArgs) {
   const inheritedExecArgs = Array.isArray(process.execArgv) ? [...process.execArgv] : [];
   const hasTsRuntimeInParent = inheritedExecArgs.some((arg) => /tsx|ts-node/i.test(arg));
-  const nodeArgs = hasTsRuntimeInParent ? [...inheritedExecArgs, options.scriptPath, ...cliArgs] : ["--import", "tsx", options.scriptPath, ...cliArgs];
-  const child = spawn2(
-    process.execPath,
-    nodeArgs,
-    {
-      cwd: options.cwd || process.cwd(),
-      stdio: ["ignore", "pipe", "pipe", "ipc"],
-      env: {
-        ...process.env,
-        TASK_ID: options.task.id,
-        TASK_NAME: options.task.task,
-        TASK_OPID: options.task.opid || ""
-      }
-    }
+  return hasTsRuntimeInParent ? [...inheritedExecArgs, scriptPath, ...cliArgs] : ["--import", "tsx", scriptPath, ...cliArgs];
+}
+function resolveTasksTableName(context) {
+  return context.tasksQueueName || context.params?.get?.("table") || "tasks";
+}
+function announceIpcFileLogsTarget(context, options) {
+  if (!options.ipcFileLogs) return;
+  const logsDir = resolveIpcFileLogsDir(context, options.ipcFileLogs);
+  const enabledRaw = context.params?.get?.("tasksLogsEnabled");
+  const logsEnabled = enabledRaw === void 0 ? true : !!enabledRaw;
+  context.logger.info?.(
+    `[tasks] IPC file logs: ${logsDir}` + (logsEnabled ? "" : " (tasksLogsEnabled=false; not persisted)")
   );
-  let stdout = "";
-  let stderr = "";
-  let workerResult = null;
-  let hadErrorMessage = false;
-  const prefix = formatChildLogPrefix(options.task);
-  const db = context.db;
-  const tasksTable = context.params?.get?.("table") || "tasks";
-  let progressWriteChain = Promise.resolve();
-  let progressCallbackChain = Promise.resolve();
-  const updateProgress = (text) => {
-    if (!db || !text || !text.trim()) return;
-    progressWriteChain = progressWriteChain.then(async () => {
-      await db(tasksTable).where({ id: options.task.id }).update({ progress: text.slice(0, 4e3) });
-    }).catch((error) => {
-      context.logger.warn?.(
-        `[tasks] failed to update progress for task=${options.task.id}: ${error?.message ?? String(error)}`
-      );
-    });
-    if (options.onProgress) {
-      progressCallbackChain = progressCallbackChain.then(async () => {
-        await options.onProgress?.(text.slice(0, 4e3));
-      }).catch((error) => {
-        context.logger.warn?.(
-          `[tasks] reportProgress callback failed for task=${options.task.id}: ${error?.message ?? String(error)}`
-        );
+}
+function createSerializedQueue() {
+  let chain = Promise.resolve();
+  return {
+    push(fn) {
+      chain = chain.then(fn, () => {
+      }).catch(() => {
+      });
+      return chain;
+    },
+    drain() {
+      return chain.catch(() => {
       });
     }
   };
-  const payloadToProgressText = (payload) => {
-    if (!payload) return "";
-    if (typeof payload === "string") return payload;
-    if (typeof payload.message === "string" && payload.level === "progress" && payload.count !== void 0 && payload.total !== void 0) {
-      const pfx = payload.prefix ? `${payload.prefix} ` : "";
-      return `${pfx}${payload.message} ${payload.count}/${payload.total}`;
-    }
-    if (typeof payload.message === "string") return payload.message;
-    if (payload.level === "progress" && payload.count !== void 0 && payload.total !== void 0) {
-      const pfx = payload.prefix ? `${payload.prefix} ` : "";
-      return `${pfx}${payload.count}/${payload.total}`;
-    }
-    return "";
+}
+async function runNodeTaskScript(context, options) {
+  const cliArgs = toCliArgs(["--route=ipc", "--mode=json", ...options.args || []]);
+  const nodeArgs = buildNodeArgs(options.scriptPath, cliArgs);
+  const child = spawn2(process.execPath, nodeArgs, {
+    cwd: options.cwd || process.cwd(),
+    stdio: ["ignore", "pipe", "pipe", "ipc"],
+    env: {
+      ...process.env,
+      TASK_ID: options.task.id,
+      TASK_NAME: options.task.name,
+      TASK_OPID: options.task.opid || ""
+    }
+  });
+  announceIpcFileLogsTarget(context, options);
+  const prefix = formatChildLogPrefix(options.task);
+  const tasksTable = resolveTasksTableName(context);
+  const progressQueue = createSerializedQueue();
+  const state = {
+    stdout: "",
+    stderr: "",
+    workerResult: null,
+    hadErrorMessage: false
   };
-  child.stdout.on("data", (chunk) => {
+  const writeProgress = (text) => {
+    const trimmed = typeof text === "string" ? text.slice(0, MAX_PROGRESS_TEXT_LEN) : "";
+    if (!trimmed) return;
+    progressQueue.push(async () => {
+      const db = context.db;
+      if (db) {
+        try {
+          await db(tasksTable).where({ id: options.task.id }).update({ progress: trimmed });
+        } catch (error) {
+          context.logger.warn?.(
+            `[tasks] failed to update progress for task=${options.task.id}: ${error?.message ?? String(error)}`
+          );
+        }
+      }
+      if (options.onProgress) {
+        try {
+          await options.onProgress(trimmed);
+        } catch (error) {
+          context.logger.warn?.(
+            `[tasks] reportProgress callback failed for task=${options.task.id}: ${error?.message ?? String(error)}`
+          );
+        }
+      }
+    });
+  };
+  child.stdout?.on("data", (chunk) => {
     const text = String(chunk);
-    stdout += text;
+    state.stdout += text;
     if (text.trim()) {
       context.logger.info?.(`[child:${prefix}] ${text.trimEnd()}`);
-      updateProgress(text.trim().replace(/\s+/g, " ").slice(0, 400));
     }
   });
-  child.stderr.on("data", (chunk) => {
+  child.stderr?.on("data", (chunk) => {
     const text = String(chunk);
-    stderr += text;
+    state.stderr += text;
     if (text.trim()) {
       context.logger.warn?.(`[child:${prefix}] ${text.trimEnd()}`);
     }
   });
   child.on("message", (message) => {
     if (message && typeof message === "object" && "__taskWorkerResult" in message) {
-      workerResult = message.__taskWorkerResult;
+      state.workerResult = message.__taskWorkerResult;
       return;
     }
     if (message && typeof message === "object") {
       const level = typeof message.level === "string" ? message.level.toLowerCase() : "";
       if (level === "error" || level === "fatal") {
-        hadErrorMessage = true;
+        state.hadErrorMessage = true;
       }
     }
-    appendTaskIpcLog(context, options.task, message);
-    const progressText = payloadToProgressText(message);
-    if (progressText) {
-      updateProgress(progressText);
-      if (typeof message === "object" && message?.level === "progress" && message.count !== void 0 && message.total !== void 0) {
-        const countNum = Number(String(message.count).trim());
-        const totalNum = Number(message.total);
-        if (Number.isFinite(countNum) && Number.isFinite(totalNum) && totalNum > 0) {
-          context.logger.progress(message.message || "progress", {
-            prefix: message.prefix || prefix,
-            count: countNum,
-            total: totalNum
-          });
-        } else {
-          context.logger.info?.(`[child:${prefix}] ${progressText}`);
-        }
-      } else {
-        context.logger.info?.(`[child:${prefix}] ${progressText}`);
-      }
+    appendTaskIpcLog(context, options.task, message, options.ipcFileLogs);
+    try {
+      options.onChildIpcMessage?.(message);
+    } catch (e) {
+      context.logger.warn?.(`[tasks] onChildIpcMessage failed: ${e?.message ?? String(e)}`);
+    }
+    if (isProgressPayload(message)) {
+      context.logger.progress(message.message || "progress", {
+        prefix: message.prefix || prefix,
+        count: Number(message.count),
+        total: Number(message.total)
+      });
+      writeProgress(formatProgressText(message, prefix));
+      return;
     }
+    forwardChildLogToParent(context, prefix, message);
   });
   return await new Promise((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 getDb3(context) {
@@ -5033,22 +5923,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) {
@@ -5066,18 +5947,20 @@ async function signalRunningTasksStop(context, runningTaskInstances, allowanceMs
 }
 async function executeClaimedTask(context, tasksTable, historyTable, row, registry, runningTaskInstances) {
   const db = getDb3(context);
-  const taskName = row.task;
+  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,
@@ -5085,7 +5968,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 {
@@ -5112,13 +5996,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");
@@ -5133,19 +6020,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({
@@ -5153,7 +6053,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
       });
@@ -5165,58 +6066,93 @@ 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) {
+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).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);
+  let query = db(tasksTable).where({ status: "idle" }).where(function() {
+    this.whereNull("service_group").orWhere({ service_group: serviceGroup });
+  }).orderByRaw("CASE WHEN past_due IS NULL THEN 1 ELSE 0 END ASC").orderBy([{ column: "priority", order: "asc" }]).orderByRaw("CASE WHEN completed_at IS NULL THEN 0 ELSE 1 END ASC").orderBy([{ column: "completed_at", order: "asc" }, { column: "created_at", order: "asc" }]).limit(scanLimit);
   if (taskNames && taskNames.length > 0) {
-    query = query.whereIn("task", taskNames);
+    query = query.whereIn("name", taskNames);
+  }
+  if (runnerIdentity) {
+    query = query.where(function() {
+      this.whereNull("service_name").orWhere({ service_name: runnerIdentity.service_name });
+    }).where(function() {
+      this.whereNull("instance_number").orWhere({ instance_number: runnerIdentity.instance_number });
+    }).where(function() {
+      this.whereNull("server_name").orWhere({ server_name: runnerIdentity.server_name });
+    });
+  } else {
+    query = query.whereNull("service_name").whereNull("instance_number").whereNull("server_name");
   }
   const candidates = await query;
+  shuffleTaskRowsInPlace(candidates);
   for (const row of candidates) {
     if (!row.past_due && row.schedule && !timeMatcher(row.schedule)) {
       continue;
     }
-    const TaskClass = registry.get(row.task);
-    if (TaskClass) {
-      const taskInstance = new TaskClass(context, row);
-      const reason = taskInstance.cantRunReason ? await taskInstance.cantRunReason() : null;
-      if (reason) {
-        if (!row.past_due) {
-          await db(tasksTable).where({ id: row.id }).update({
-            past_due: db.fn.now(),
-            progress: String(reason)
-          });
-        }
-        continue;
+    const TaskClass = registry.get(row.name);
+    if (!TaskClass) {
+      continue;
+    }
+    const taskInstance = new TaskClass(context, row);
+    const reason = taskInstance.cantRunReason ? await taskInstance.cantRunReason() : null;
+    if (reason) {
+      if (!row.past_due) {
+        await db(tasksTable).where({ id: row.id }).update({
+          past_due: db.fn.now(),
+          progress: String(reason)
+        });
       }
+      continue;
     }
-    const updated = await db(tasksTable).where({ id: row.id }).whereNull("started_at").whereNull("paused_at").update({ started_at: db.fn.now() }).returning("*");
+    const claimPatch = {
+      started_at: db.fn.now(),
+      status: "running",
+      status_changed_at: db.fn.now()
+    };
+    if (runnerIdentity) {
+      claimPatch.service_name = runnerIdentity.service_name;
+      claimPatch.server_name = runnerIdentity.server_name;
+      claimPatch.instance_number = runnerIdentity.instance_number;
+    }
+    const updated = await db(tasksTable).where({ id: row.id, status: "idle" }).update(claimPatch).returning("*");
     const claimed = Array.isArray(updated) ? updated[0] : null;
     if (claimed) return claimed;
   }
   return null;
 }
 async function runTasksLoop(context, options) {
-  const queue = options.queue ?? "tasks";
+  const queueName = options.queueName ?? "tasks";
   const target = options.target;
   const pollMs = options.pollMs ?? 1e3;
-  const maxParallel = options.maxParallel ?? 1;
+  const claimJitterMs = options.claimJitterMs ?? 0;
+  const maxParallel = options.maxParallel ?? 32;
   const scanLimit = options.scanLimit ?? 100;
   const allowedTasks = normalizeAllowedTasks(options.allowedTasks);
   const registry = normalizeRegistry(options.registry);
-  const { tasksTable, historyTable } = queueToTableNames(queue);
+  const { tasksTable, historyTable } = queueToTableNames(queueName);
   if (!target) throw new Error("runTasksLoop: target is required");
+  context.tasksQueueName = queueName;
   const runningPromises = /* @__PURE__ */ new Set();
   const runningTaskInstances = /* @__PURE__ */ new Map();
   let runningStopControlPromise = null;
   let stopRequested = false;
   let stopAllowanceMs = 5e3;
-  context.__tasksRunnerStop = false;
+  context.tasksRunnerStop = false;
   let registryReg = null;
   let registryInterval = null;
+  let runnerIdentity = null;
   const hbGroup = options.runnerServiceGroup?.trim();
   if (hbGroup) {
-    const identityDir = options.runnerIdentityDir ?? "./data/runner-identities";
     const hbIntervalMs = options.runnerHeartbeatIntervalMs ?? 1e4;
     const staleMs = options.runnerHeartbeatStaleMs ?? 45e3;
     const defaultMeta = {
@@ -5224,16 +6160,21 @@ async function runTasksLoop(context, options) {
       allowedTasks: allowedTasks?.length ? allowedTasks.join(",") : "all"
     };
     registryReg = await registerInServicesRegistry(context, {
-      queue,
+      queueName,
       target,
       serviceGroup: hbGroup,
       serviceName: options.runnerServiceName,
-      identityDir,
+      instanceNumber: options.runnerInstanceNumber,
       staleMs,
       groupMaxInstances: options.runnerGroupMaxInstances,
       enforceMaxInstances: options.runnerEnforceMaxInstances ?? true,
       metadata: options.runnerMetadata ?? defaultMeta
     });
+    runnerIdentity = {
+      service_name: registryReg.serviceName,
+      server_name: os3.hostname(),
+      instance_number: registryReg.instanceNumber
+    };
     registryInterval = setInterval(() => {
       void touchServicesRegistry(context, registryReg).catch((err) => {
         context.logger.warn?.(`[services-registry] touch failed: ${err?.message ?? String(err)}`);
@@ -5241,7 +6182,7 @@ async function runTasksLoop(context, options) {
     }, hbIntervalMs);
   }
   try {
-    while (!context.isStop() && !stopRequested && !context.__tasksRunnerStop) {
+    while (!context.isStop() && !stopRequested && context.tasksRunnerStop !== true) {
       if (!runningStopControlPromise) {
         const claimedStopTask = await claimNextRunnableTask(
           context,
@@ -5249,7 +6190,8 @@ async function runTasksLoop(context, options) {
           target,
           registry,
           10,
-          ["stopRunner", "stop"]
+          ["stopRunner", "stop"],
+          runnerIdentity
         );
         if (claimedStopTask) {
           runningStopControlPromise = executeClaimedTask(
@@ -5263,7 +6205,7 @@ async function runTasksLoop(context, options) {
             if (outcome.stopRunnerRequested && !stopRequested) {
               stopRequested = true;
               stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
-              context.__tasksRunnerStop = true;
+              context.tasksRunnerStop = true;
               await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
             }
           }).finally(() => {
@@ -5271,6 +6213,9 @@ async function runTasksLoop(context, options) {
           });
         }
       }
+      if (claimJitterMs > 0) {
+        await sleepMs(Math.floor(Math.random() * (claimJitterMs + 1)));
+      }
       while (runningPromises.size < maxParallel) {
         const claimed = await claimNextRunnableTask(
           context,
@@ -5278,14 +6223,15 @@ async function runTasksLoop(context, options) {
           target,
           registry,
           scanLimit,
-          allowedTasks
+          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(() => {
@@ -5293,7 +6239,16 @@ async function runTasksLoop(context, options) {
         });
         runningPromises.add(p);
       }
-      await sleepMs(pollMs);
+      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)]);
+      }
     }
     if (context.isStop() && !stopRequested) {
       await signalRunningTasksStop(context, runningTaskInstances, 5e3);
@@ -5329,89 +6284,130 @@ async function runTasksLoop(context, options) {
 }
 async function waitForTaskResult(context, taskId, options = {}) {
   const db = getDb3(context);
-  const queue = options.queue ?? "tasks";
+  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;
-  runnerServiceGroup;
-  runnerServiceName;
-  runnerIdentityDir;
-  runnerHeartbeatIntervalMs;
-  runnerHeartbeatStaleMs;
-  runnerGroupMaxInstances;
-  runnerEnforceMaxInstances;
-  runnerMetadata;
+  /**
+   * @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.runnerIdentityDir = options.runnerIdentityDir;
+    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",
       runnerServiceGroup: "string",
       runnerServiceName: "string",
-      runnerIdentityDir: "string default ./data/runner-identities",
+      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,
-      runnerIdentityDir: discovered.runnerIdentityDir,
+      runnerInstanceNumber: discovered.runnerInstanceNumber,
       runnerHeartbeatIntervalMs: discovered.runnerHeartbeatIntervalMs,
       runnerHeartbeatStaleMs: discovered.runnerHeartbeatStaleMs,
       runnerGroupMaxInstances: discovered.runnerGroupMaxInstances,
@@ -5420,24 +6416,39 @@ var TasksManager = class _TasksManager {
     };
     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,
       runnerServiceGroup: options.runnerServiceGroup ?? this.runnerServiceGroup,
       runnerServiceName: options.runnerServiceName ?? this.runnerServiceName,
-      runnerIdentityDir: options.runnerIdentityDir ?? this.runnerIdentityDir,
+      runnerInstanceNumber: options.runnerInstanceNumber ?? this.runnerInstanceNumber,
       runnerHeartbeatIntervalMs: options.runnerHeartbeatIntervalMs ?? this.runnerHeartbeatIntervalMs,
       runnerHeartbeatStaleMs: options.runnerHeartbeatStaleMs ?? this.runnerHeartbeatStaleMs,
       runnerGroupMaxInstances: options.runnerGroupMaxInstances ?? this.runnerGroupMaxInstances,
@@ -5447,8 +6458,9 @@ var TasksManager = class _TasksManager {
   }
 };
 export {
+  AbstractTask,
   Args,
-  Box5 as Box,
+  Box4 as Box,
   Db,
   Divider,
   FileDatabase,
@@ -5461,14 +6473,16 @@ export {
   MultiColumnListComponent,
   MultiColumnListWithPreviewComponent,
   Params,
-  React5 as React,
+  React2 as React,
+  S3,
+  SERVICE_TASK_NAMES,
   ScreenBody,
   ScreenContainer,
   ScreenDivider,
   ScreenFooter,
   ScreenRow,
   ScreenTitle,
-  TaskMaster,
+  TaskGetLogs,
   TaskPing,
   TaskSampleProcess,
   TaskShellCommand,
@@ -5483,17 +6497,17 @@ export {
   buildBreadcrumb,
   buildDetailBreadcrumb,
   buildFooter,
-  dbConnect,
-  dbFindAndConnect,
-  dbInit,
+  convertPattern,
   defaultFileSynopsisFunction,
   defaultTasksRegistry,
   defaultVersionSynopsisFunction,
   enqueueStopTask,
   enqueueTask,
   ensureTaskTables,
+  flushTaskIpcLogs,
   getArgsInstance,
   createElement2 as h,
+  ipcFileLogsTableNameForSourceResource,
   joiEdateType,
   joiStringArrayType,
   listServicesRegistry as listAliveRunnerHeartbeats,
@@ -5501,14 +6515,22 @@ export {
   listSources,
   listTables,
   load,
+  matchesParsedPattern,
+  memo,
+  mergeAllowedTasksWithServiceTasks,
+  nextTimeMatch,
+  normalizeAllowedTasks,
   organizeFooterMessages,
   queueToTableNames,
+  readTaskIpcLogsSnapshot,
   registerInServicesRegistry,
   registerInServicesRegistry as registerRunnerHeartbeat,
+  resolveAsterisks,
+  resolveIpcFileLogsDir,
+  resolveRanges,
+  resolveSteps,
   runNodeTaskScript,
   runTasksLoop,
-  servicesRegistryTable as runnerHeartbeatsTable,
-  servicesRegistryTable,
   setupContext,
   showListScreen,
   showMenuScreen,
@@ -5516,6 +6538,8 @@ export {
   showMultiColumnListWithPreviewScreen,
   showScreen,
   showWordGridScreen,
+  taskHistoryInsertFromQueueRow,
+  timeMatcher,
   touchServicesRegistry as touchRunnerHeartbeat,
   touchServicesRegistry,
   unregisterServicesRegistry as unregisterRunnerHeartbeat,
@@ -5523,10 +6547,11 @@ export {
   updateServicesRegistryMetadata,
   updateTaskProgress,
   useCallback,
-  useEffect3 as useEffect,
+  useEffect2 as useEffect,
   useInput2 as useInput,
+  useLayoutEffect,
   useMemo,
-  useRef3 as useRef,
+  useRef2 as useRef,
   useState3 as useState,
   waitForTaskResult
 };