@nmakarov/cli-toolkit 0.16.0 → 0.21.0

package/dist/index.js

@@ -901,11 +901,11 @@ function buildBreadcrumb(parts) {
   if (parts.length === 1) return parts[0];
   return parts.slice(1).map((part) => `\u2190  ${part}`).join("  ");
 }
-function buildDetailBreadcrumb(path4, suffix = "") {
-  if (path4.length <= 1) {
-    return suffix ? `\u2190  ${suffix}` : path4[0] || "";
+function buildDetailBreadcrumb(path5, suffix = "") {
+  if (path5.length <= 1) {
+    return suffix ? `\u2190  ${suffix}` : path5[0] || "";
   }
-  const breadcrumb = buildBreadcrumb(path4);
+  const breadcrumb = buildBreadcrumb(path5);
   return suffix ? `${breadcrumb} ${suffix}` : breadcrumb;
 }
 var init_utils = __esm({
@@ -1876,7 +1876,7 @@ var Params = class _Params {
         throw new ParamError(`default value "${defValObj.value}" type mismatch`);
       }
       type = type.default(defValObj.value);
-    } else if (str.match(/required/)) {
+    } else if (str.match(/\s*required\s*/)) {
       type = type.required();
     } else {
       type = type.optional();
@@ -1952,6 +1952,8 @@ var Params = class _Params {
   /**
    * Get all parameters from definitions (main script).
    * Same as getAllForModule("script", defs). Processes left-to-right for cross-parameter references.
+   * Libraries should use {@link getAllForModule} with an explicit module name (or {@link runWithModule}
+   * around {@link get}) so --showUsedParams groups usage correctly.
    */
   getAll(defs) {
     return this.getAllForModule("script", defs);
@@ -1988,6 +1990,19 @@ var Params = class _Params {
       this._currentModule = prev;
     }
   }
+  /**
+   * Run a callback with {@link _currentModule} set so single {@link get} calls are tracked
+   * under the same module (for --showUsedParams / getFiguredByModule).
+   */
+  runWithModule(moduleName, fn) {
+    const prev = this._currentModule;
+    this._currentModule = moduleName;
+    try {
+      return fn();
+    } finally {
+      this._currentModule = prev;
+    }
+  }
   /**
    * Infer module name from call stack: first caller outside params/index gives path like .../src/<moduleName>/...
    */
@@ -2001,9 +2016,9 @@ var Params = class _Params {
       if (!parenMatch) continue;
       const parts = parenMatch[1].split(":");
       if (parts.length < 3) continue;
-      const path4 = parts.slice(0, -2).join(":").replace(/^file:\/\//, "");
-      if (!path4 || path4.includes(paramsIndexPath)) continue;
-      const srcMatch = path4.match(/[/\\]src[/\\]([^/\\]+)(?:[/\\]|$)/);
+      const path5 = parts.slice(0, -2).join(":").replace(/^file:\/\//, "");
+      if (!path5 || path5.includes(paramsIndexPath)) continue;
+      const srcMatch = path5.match(/[/\\]src[/\\]([^/\\]+)(?:[/\\]|$)/);
       if (srcMatch) return srcMatch[1];
     }
     return "script";
@@ -2358,7 +2373,7 @@ var FileDatabase = class _FileDatabase {
     const versions = await this.getVersions();
     while (versions.length > this.maxVersions) {
       const versionToDelete = path3.resolve(this.getDestinationPath(), versions.shift());
-      this.logger.debug?.(`[FileDatabase] Deleting old version: ${versionToDelete}`);
+      this.logger.silly?.(`[FileDatabase] Deleting old version: ${versionToDelete}`);
       await fs3.promises.rm(versionToDelete, { recursive: true, force: true });
     }
     return versionName;
@@ -2636,7 +2651,7 @@ var FileDatabase = class _FileDatabase {
     };
     this.metadata.files.push(fileEntry);
     this.lastFileData = null;
-    this.logger.debug?.(`[FileDatabase] Created new file: ${fileEntry.fileName}, fileNumber: ${this.currentFileNumber}`);
+    this.logger.silly?.(`[FileDatabase] Created new file: ${fileEntry.fileName}, fileNumber: ${this.currentFileNumber}`);
   }
   /**
    * Figure out what data to write and which file to use (for pagination)
@@ -2669,7 +2684,7 @@ var FileDatabase = class _FileDatabase {
       const filesBeforeCreate = this.metadata.files.length;
       this.makeNewFile();
       newlyCreatedFileIndex = filesBeforeCreate;
-      this.logger.debug?.(`[FileDatabase] Creating new file for unique custom metadata combination, fileNumber: ${this.currentFileNumber}`);
+      this.logger.silly?.(`[FileDatabase] Creating new file for unique custom metadata combination, fileNumber: ${this.currentFileNumber}`);
     } else if (this.metadata.files.length === 0) {
       this.makeNewFile();
     }
@@ -2718,7 +2733,7 @@ var FileDatabase = class _FileDatabase {
       dataLeftOver = null;
     }
     const fileName = this.metadata.files[this.metadata.files.length - 1].fileName;
-    this.logger.debug?.(
+    this.logger.silly?.(
       `[FileDatabase] figureOutDataAndFileToWrite: filename=${fileName}, forceNewFile=${forceNewFile}, targetFileIndex=${targetFileIndex}, dataToWrite.length=${Array.isArray(dataToWrite) ? dataToWrite.length : "N/A"}, lastFileRecordsCount=${lastFileRecordsCount}`
     );
     return { dataToWrite, dataLeftOver, fileName };
@@ -2773,7 +2788,7 @@ var FileDatabase = class _FileDatabase {
     this.metadata.modifiedAt = (/* @__PURE__ */ new Date()).toISOString();
     this.metadata.dataType = detectDataType(dataToWrite);
     this.metadata.totalRecords = this.metadata.files.reduce((sum, file) => sum + (file.recordsCount || 0), 0);
-    this.logger.debug?.(
+    this.logger.silly?.(
       `[FileDatabase] Updated metadata for file ${currentFile.fileName}: recordsCount=${recordsCount}, totalRecords=${this.metadata.totalRecords}`
     );
   }
@@ -2797,7 +2812,7 @@ var FileDatabase = class _FileDatabase {
     }
     try {
       await fs3.promises.writeFile(filePath, serializedData, "utf8");
-      this.logger.debug?.(`[FileDatabase] Wrote ${bytesToHumanReadable(requiredBytes)} to ${filePath}`);
+      this.logger.silly?.(`[FileDatabase] Wrote ${bytesToHumanReadable(requiredBytes)} to ${filePath}`);
     } catch (error) {
       throw new FileDatabaseError(`Failed to write file ${filePath}: ${error.message}`);
     }
@@ -2879,7 +2894,8 @@ var FileDatabase = class _FileDatabase {
           this.useMetadata = format.hasMetadata;
         }
         if (this.useMetadata) {
-          const metadataPath = path3.join(this.getDestinationPath(), "metadata.json");
+          const destPath = this.getDestinationPath();
+          const metadataPath = path3.join(destPath, "metadata.json");
           if (fs3.existsSync(metadataPath)) {
             try {
               const rawData = await fs3.promises.readFile(metadataPath, "utf8");
@@ -2893,7 +2909,9 @@ var FileDatabase = class _FileDatabase {
               throw new FileDatabaseError(`Failed to read metadata: ${e.message}`);
             }
           } else {
-            throw new FileDatabaseError("[FileDatabase] No metadata found in non-versioned mode");
+            throw new FileDatabaseError(
+              `[FileDatabase] No metadata found in non-versioned mode. Looked for: ${metadataPath} (table path: ${destPath})`
+            );
           }
         } else {
           this.metadata = await this.figureMetadataFromVersionFiles("");
@@ -2910,6 +2928,13 @@ var FileDatabase = class _FileDatabase {
    * Write data to the file database
    */
   async write(data, options = {}) {
+    if (options.filename) {
+      const destPath2 = this.getDestinationPath();
+      await ensurePath(destPath2);
+      const filePath = path3.join(destPath2, options.filename);
+      await this.safeWrite(filePath, data);
+      return;
+    }
     if (options.forceNewVersion && !this.versioned) {
       throw new FileDatabaseError("Cannot use forceNewVersion in non-versioned mode");
     }
@@ -2933,17 +2958,17 @@ var FileDatabase = class _FileDatabase {
         });
         if (matches) {
           targetFileIndex = i;
-          this.logger.debug?.(`[FileDatabase] Found existing file with matching custom metadata: ${fileEntry.fileName}, metadata: ${JSON.stringify(options.customMetadata)}`);
+          this.logger.silly?.(`[FileDatabase] Found existing file with matching custom metadata: ${fileEntry.fileName}, metadata: ${JSON.stringify(options.customMetadata)}`);
           break;
         } else {
-          this.logger.debug?.(`[FileDatabase] File ${fileEntry.fileName} does not match custom metadata: ${JSON.stringify(options.customMetadata)}`);
+          this.logger.silly?.(`[FileDatabase] File ${fileEntry.fileName} does not match custom metadata: ${JSON.stringify(options.customMetadata)}`);
         }
       }
       if (targetFileIndex === null) {
-        this.logger.debug?.(`[FileDatabase] No existing file found with custom metadata: ${JSON.stringify(options.customMetadata)}, will create new file`);
+        this.logger.silly?.(`[FileDatabase] No existing file found with custom metadata: ${JSON.stringify(options.customMetadata)}, will create new file`);
       }
     } else {
-      this.logger.debug?.(`[FileDatabase] No custom metadata provided, will create new file`);
+      this.logger.silly?.(`[FileDatabase] No custom metadata provided, will create new file`);
     }
     if (targetFileIndex !== null) {
       const targetFile = this.metadata.files[targetFileIndex];
@@ -2972,7 +2997,17 @@ var FileDatabase = class _FileDatabase {
    * Read data from the file database
    */
   async read(options = {}) {
-    const { version, nextPage = false, pageSize } = options;
+    const { version, nextPage = false, pageSize, filename } = options;
+    if (filename) {
+      const destPath = this.getDestinationPath(version);
+      const filePath = path3.join(destPath, filename);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        return JSON.parse(rawData);
+      } catch (error) {
+        throw new FileDatabaseError(`Failed to read file ${filename}: ${error.message}`);
+      }
+    }
     await this.prepare({ read: true, version });
     const isNonPaginatedData = this.metadata.dataType === "text" || this.metadata.dataType === "xml" || this.metadata.dataType === "json-object";
     if (isNonPaginatedData) {
@@ -3053,6 +3088,67 @@ var FileDatabase = class _FileDatabase {
     this.currentRecord = 0;
     this.hasReadFirstPage = false;
   }
+  /**
+   * List filenames in the table directory.
+   * For catalog/key-value usage (files written with { filename }).
+   * Returns data file names (.json, .txt, .xml) excluding metadata.json.
+   */
+  async listFilenames() {
+    const destPath = this.versioned && this.currentVersion ? path3.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    try {
+      const entries = await fs3.promises.readdir(destPath, { withFileTypes: true });
+      return entries.filter((e) => e.isFile() && e.name !== "metadata.json" && /\.(json|txt|xml)$/i.test(e.name)).map((e) => e.name);
+    } catch (err) {
+      if (err?.code === "ENOENT") return [];
+      throw new FileDatabaseError(`Failed to list files: ${err.message}`);
+    }
+  }
+  /**
+   * Remove a file from the table directory (catalog mode).
+   * Use with listFilenames() to manage individual files.
+   */
+  async removeFile(filename) {
+    const destPath = this.versioned && this.currentVersion ? path3.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    const filePath = path3.join(destPath, filename);
+    try {
+      await fs3.promises.unlink(filePath);
+    } catch (err) {
+      if (err?.code === "ENOENT") return;
+      throw new FileDatabaseError(`Failed to remove file ${filename}: ${err.message}`);
+    }
+  }
+  /**
+   * Remove a file and its metadata entry (non-versioned mode with useMetadata).
+   * Use with findData() to get fileName, then call removeFileEntry to delete.
+   */
+  async removeFileEntry(filename) {
+    if (this.versioned) {
+      throw new FileDatabaseError("removeFileEntry is only supported in non-versioned mode");
+    }
+    await this.prepare({ read: true });
+    const idx = this.metadata.files.findIndex((f) => f.fileName === filename);
+    if (idx === -1) {
+      throw new FileDatabaseError(`File entry ${filename} not found in metadata`);
+    }
+    const entry = this.metadata.files[idx];
+    const recordsCount = entry.recordsCount || 0;
+    this.metadata.files.splice(idx, 1);
+    this.metadata.totalRecords = Math.max(0, (this.metadata.totalRecords || 0) - recordsCount);
+    const destPath = this.getDestinationPath();
+    const filePath = path3.join(destPath, filename);
+    try {
+      await fs3.promises.unlink(filePath);
+    } catch (err) {
+      if (err?.code === "ENOENT") {
+        this.logger.warn?.(`[FileDatabase] File ${filename} already missing on disk`);
+      } else {
+        throw new FileDatabaseError(`Failed to remove file ${filename}: ${err.message}`);
+      }
+    }
+    if (this.useMetadata) {
+      await this.saveVersionMetadata(this.metadata);
+    }
+  }
   /**
    * Set file-level synopsis calculation function
    */
@@ -3524,7 +3620,7 @@ async function dbFindAndConnect(context, dbNameOrConnectionString) {
       dbConnectionString: "string",
       dbProfile: "boolean default false"
     };
-    const paramsConfig = context.params.getAllForModule(defs);
+    const paramsConfig = context.params.getAll(defs);
     dbName = paramsConfig.dbName;
     dbConnectionString = paramsConfig.dbConnectionString;
     dbProfile = paramsConfig.dbProfile;
@@ -3586,6 +3682,7 @@ var ALL_LEVELS = [
   "response",
   "progress"
 ];
+var DEFAULT_LEVELS = ALL_LEVELS.filter((l) => l !== "silly");
 var MAX_LEVEL_LENGTH = Math.max(...ALL_LEVELS.map((level) => level.toUpperCase().length));
 var LEVEL_COLORS = {
   error: chalk.red.bold,
@@ -3671,7 +3768,7 @@ var Logger = class _Logger {
       silent: false,
       showLevel: false,
       timestamp: false,
-      levels: ALL_LEVELS,
+      levels: DEFAULT_LEVELS,
       progressTimes: false,
       progressThrottle: void 0
     };
@@ -3831,15 +3928,17 @@ var Logger = class _Logger {
   }
   normalizeLevels(levels) {
     if (!levels || !levels.length) {
-      return ALL_LEVELS;
+      return DEFAULT_LEVELS;
     }
-    const includes = levels.filter((level) => !level.startsWith("-"));
-    const excludes = levels.filter((level) => level.startsWith("-")).map((level) => level.slice(1));
-    const unknown = [...includes, ...excludes].filter((level) => !ALL_LEVELS.includes(level));
+    const tokens = levels.map((t) => String(t).trim()).filter(Boolean);
+    const explicitIncludes = tokens.filter((t) => !t.startsWith("+") && !t.startsWith("-")).map((t) => t);
+    const addIncludes = tokens.filter((t) => t.startsWith("+")).map((t) => t.slice(1));
+    const excludes = tokens.filter((t) => t.startsWith("-")).map((t) => t.slice(1));
+    const unknown = [...explicitIncludes, ...addIncludes, ...excludes].filter((level) => !ALL_LEVELS.includes(level));
     if (unknown.length) {
       console.warn(`[Logger] Unknown level(s): ${unknown.join(", ")}`);
     }
-    const base = includes.length ? includes : ALL_LEVELS;
+    const base = explicitIncludes.length ? explicitIncludes : Array.from(/* @__PURE__ */ new Set([...DEFAULT_LEVELS, ...addIncludes]));
     return base.filter((level) => !excludes.includes(level));
   }
   isValidMode(mode) {
@@ -3897,6 +3996,1456 @@ function setup(opts = {}) {
 function setupContext(opts = {}) {
   return setup(opts);
 }
+
+// src/utils/core-utils.ts
+function sleepMs(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function toJsonColumn(value) {
+  if (value === void 0 || value === null) return null;
+  return JSON.stringify(value);
+}
+
+// src/tasks/servicesRegistry.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import os from "os";
+import path4 from "path";
+
+// src/tasks/taskUtils.ts
+import { randomUUID } from "crypto";
+function getDb(context) {
+  const db = context.db;
+  if (!db) {
+    throw new Error("Tasks component requires context.db. Initialize DB first and attach to 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.`);
+  }
+  return {
+    tasksTable: queue,
+    historyTable: `${queue}_history`
+  };
+}
+function servicesRegistryTable(queue) {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(queue)) {
+    throw new Error(`Invalid queue name "${queue}". Use letters, numbers, underscore only.`);
+  }
+  return `${queue}_services_registry`;
+}
+async function ensureTaskTables(context, options = {}) {
+  const queue = options.queue ?? "tasks";
+  const recreate = options.recreate ?? false;
+  const db = getDb(context);
+  const { tasksTable, historyTable } = queueToTableNames(queue);
+  const needsTasks = recreate ? true : !await db.tableExists(tasksTable);
+  const needsHistory = recreate ? true : !await db.tableExists(historyTable);
+  if (recreate) {
+    await db.schema.dropTableIfExists(historyTable);
+    await db.schema.dropTableIfExists(tasksTable);
+  }
+  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`);
+    });
+  }
+  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`);
+    });
+  }
+  const registryTable = servicesRegistryTable(queue);
+  const needsRegistry = !await db.tableExists(registryTable);
+  if (needsRegistry) {
+    await db.schema.createTable(registryTable, (t) => {
+      t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
+      t.uuid("instance_id").notNullable().unique();
+      t.text("queue").notNullable();
+      t.text("service_group").notNullable();
+      t.text("service_name").notNullable();
+      t.text("target").notNullable();
+      t.text("hostname");
+      t.integer("pid");
+      t.json("metadata");
+      t.timestamp("created_at").notNullable().defaultTo(db.fn.now());
+      t.timestamp("last_seen_at").notNullable().defaultTo(db.fn.now());
+      t.unique(["queue", "service_name"], `${registryTable}_queue_service_name_uniq`);
+      t.index(["queue", "service_group", "last_seen_at"], `${registryTable}_queue_group_seen_idx`);
+      t.index(["queue", "last_seen_at"], `${registryTable}_queue_seen_idx`);
+    });
+  }
+}
+async function enqueueTask(context, options) {
+  const db = getDb(context);
+  const queue = options.queue ?? "tasks";
+  const { tasksTable } = queueToTableNames(queue);
+  const id = randomUUID();
+  await db(tasksTable).insert({
+    id,
+    target: options.target,
+    task: options.task,
+    params: toJsonColumn(options.params ?? null),
+    opid: options.opid ?? null,
+    priority: options.priority ?? 0,
+    schedule: options.schedule ?? null
+  });
+  return id;
+}
+async function updateTaskProgress(context, tasksTable, taskId, progress) {
+  const db = getDb(context);
+  await db(tasksTable).where({ id: taskId }).update({
+    progress: typeof progress === "string" ? progress : JSON.stringify(progress)
+  });
+}
+
+// src/tasks/servicesRegistry.ts
+function getDb2(context) {
+  const db = context.db;
+  if (!db) {
+    throw new Error("Services registry requires context.db");
+  }
+  return db;
+}
+function parseMetadataColumn(value) {
+  if (!value) return {};
+  if (typeof value === "object" && !Array.isArray(value)) return value;
+  if (typeof value === "string") {
+    try {
+      const p = JSON.parse(value);
+      return p && typeof p === "object" && !Array.isArray(p) ? p : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+var DEFAULT_GROUP_MAX_INSTANCES = {
+  intake: 1,
+  harvest: 1,
+  loader: 0,
+  photos: 0,
+  photosprocessor: 0,
+  ingest: 0
+};
+function sanitizeNamePart(raw) {
+  const s = String(raw || "").trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return s.slice(0, 80) || "runner";
+}
+function identityFilePath(identityDir, queue, serviceGroup) {
+  const safeQ = sanitizeNamePart(queue);
+  const safeG = sanitizeNamePart(serviceGroup);
+  return 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)));
+  }
+  const g = serviceGroup.trim().toLowerCase();
+  return DEFAULT_GROUP_MAX_INSTANCES[g] ?? 0;
+}
+async function countAliveInGroup(db, registryTable, queue, serviceGroup, staleMs, excludeInstanceId) {
+  const cutoff = new Date(Date.now() - staleMs);
+  let q = db(registryTable).where({ queue, service_group: serviceGroup }).where("last_seen_at", ">", cutoff);
+  if (excludeInstanceId) {
+    q = q.whereNot("instance_id", excludeInstanceId);
+  }
+  const row = await q.count("id as count").first();
+  return Number(row?.count ?? 0);
+}
+function isUniqueViolation(error) {
+  const code = error?.code ?? error?.errno;
+  return code === "23505" || String(error?.message || "").includes("duplicate key");
+}
+async function registerInServicesRegistry(context, options) {
+  const db = getDb2(context);
+  const registryTable = servicesRegistryTable(options.queue);
+  const serviceGroup = options.serviceGroup.trim();
+  if (!serviceGroup) {
+    throw new Error("registerInServicesRegistry: serviceGroup is required");
+  }
+  const identityPath = identityFilePath(options.identityDir, options.queue, serviceGroup);
+  let identity = await readIdentityFile(identityPath);
+  let instanceId = typeof identity.instanceId === "string" && identity.instanceId.trim() ? identity.instanceId.trim() : randomUUID2();
+  identity.instanceId = instanceId;
+  await writeIdentityFile(identityPath, identity);
+  const hostname = os.hostname();
+  const pid = typeof process.pid === "number" ? process.pid : null;
+  const meta = toJsonColumn(options.metadata ?? null);
+  const existing = await db(registryTable).where({ instance_id: instanceId }).first();
+  if (existing) {
+    await db(registryTable).where({ instance_id: instanceId }).update({
+      target: options.target,
+      hostname,
+      pid,
+      metadata: meta,
+      last_seen_at: db.fn.now()
+    });
+    const serviceName = String(existing.service_name);
+    identity.serviceName = serviceName;
+    await writeIdentityFile(identityPath, identity);
+    const reg = {
+      instanceId,
+      serviceName,
+      serviceGroup,
+      queue: options.queue,
+      target: options.target,
+      rowId: String(existing.id)
+    };
+    context.servicesRegistry = reg;
+    context.runnerHeartbeat = reg;
+    context.logger.info?.(
+      `[services-registry] resumed instance_id=${instanceId} name=${serviceName} group=${serviceGroup} queue=${options.queue}`
+    );
+    return {
+      instanceId,
+      serviceName,
+      serviceGroup,
+      queue: options.queue,
+      target: options.target,
+      rowId: String(existing.id),
+      registryTable
+    };
+  }
+  const maxAllowed = resolveMaxInstances(serviceGroup, options.groupMaxInstances);
+  const aliveOthers = await countAliveInGroup(
+    db,
+    registryTable,
+    options.queue,
+    serviceGroup,
+    options.staleMs,
+    instanceId
+  );
+  if (maxAllowed > 0 && aliveOthers >= maxAllowed) {
+    const msg = `[services-registry] group limit reached for "${serviceGroup}": ${aliveOthers} alive (max ${maxAllowed}, queue=${options.queue}).`;
+    if (options.enforceMaxInstances) {
+      throw new Error(msg);
+    }
+    context.logger.warn?.(`${msg} Starting anyway (runnerEnforceMaxInstances=false).`);
+  }
+  const explicitName = options.serviceName?.trim();
+  const fromFile = typeof identity.serviceName === "string" ? identity.serviceName.trim() : "";
+  const hostBase = sanitizeNamePart(hostname);
+  const groupBase = sanitizeNamePart(serviceGroup);
+  const baseCandidates = [];
+  if (explicitName) baseCandidates.push(sanitizeNamePart(explicitName));
+  if (fromFile) baseCandidates.push(sanitizeNamePart(fromFile));
+  baseCandidates.push(`${groupBase}-${hostBase}`);
+  baseCandidates.push(groupBase);
+  function* eachServiceNameCandidate(bases) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const rawBase of bases) {
+      const base = sanitizeNamePart(rawBase);
+      if (!base) continue;
+      const seq = [base];
+      for (let n = 2; n <= 500; n++) seq.push(`${base}-${n}`);
+      for (const c of seq) {
+        if (seen.has(c)) continue;
+        seen.add(c);
+        yield c;
+      }
+    }
+  }
+  let inserted;
+  for (const candidate of eachServiceNameCandidate(baseCandidates)) {
+    try {
+      const rows = await db(registryTable).insert({
+        instance_id: instanceId,
+        queue: options.queue,
+        service_group: serviceGroup,
+        service_name: candidate,
+        target: options.target,
+        hostname,
+        pid,
+        metadata: meta,
+        last_seen_at: db.fn.now()
+      }).returning(["id", "service_name"]);
+      const row = Array.isArray(rows) ? rows[0] : rows;
+      if (row) {
+        inserted = { id: String(row.id), service_name: String(row.service_name) };
+        break;
+      }
+    } catch (error) {
+      if (!isUniqueViolation(error)) {
+        throw error;
+      }
+    }
+  }
+  if (!inserted) {
+    throw new Error(
+      `[services-registry] could not allocate a unique service_name for group=${serviceGroup} queue=${options.queue} (too many collisions).`
+    );
+  }
+  identity.serviceName = inserted.service_name;
+  await writeIdentityFile(identityPath, identity);
+  const regNew = {
+    instanceId,
+    serviceName: inserted.service_name,
+    serviceGroup,
+    queue: options.queue,
+    target: options.target,
+    rowId: inserted.id
+  };
+  context.servicesRegistry = regNew;
+  context.runnerHeartbeat = regNew;
+  context.logger.info?.(
+    `[services-registry] registered instance_id=${instanceId} name=${inserted.service_name} group=${serviceGroup} queue=${options.queue} target=${options.target}`
+  );
+  return {
+    instanceId,
+    serviceName: inserted.service_name,
+    serviceGroup,
+    queue: options.queue,
+    target: options.target,
+    rowId: inserted.id,
+    registryTable
+  };
+}
+async function touchServicesRegistry(context, registration) {
+  const db = getDb2(context);
+  const hostname = os.hostname();
+  const pid = typeof process.pid === "number" ? process.pid : null;
+  await db(registration.registryTable).where({ instance_id: registration.instanceId }).update({
+    last_seen_at: db.fn.now(),
+    hostname,
+    pid
+  });
+}
+async function updateServicesRegistryMetadata(context, registration, patch) {
+  const db = getDb2(context);
+  const row = await db(registration.registryTable).where({ instance_id: registration.instanceId }).first();
+  const prev = parseMetadataColumn(row?.metadata);
+  const merged = { ...prev, ...patch };
+  await db(registration.registryTable).where({ instance_id: registration.instanceId }).update({
+    metadata: toJsonColumn(merged),
+    last_seen_at: db.fn.now()
+  });
+  context.logger.info?.(`[services-registry] metadata updated for ${registration.serviceName}`);
+}
+async function unregisterServicesRegistry(context, registration) {
+  const db = getDb2(context);
+  await db(registration.registryTable).where({ instance_id: registration.instanceId }).delete();
+  context.logger.info?.(`[services-registry] unregistered name=${registration.serviceName} instance_id=${registration.instanceId}`);
+}
+async function listServicesRegistry(context, options = { queue: "tasks" }) {
+  const db = getDb2(context);
+  const staleMs = options.staleMs ?? 6e4;
+  const cutoff = new Date(Date.now() - staleMs);
+  const table = servicesRegistryTable(options.queue);
+  let q = db(table).where("last_seen_at", ">", cutoff).orderBy([{ column: "service_group", order: "asc" }, { column: "service_name", order: "asc" }]);
+  if (options.serviceGroup?.trim()) {
+    q = q.where({ service_group: options.serviceGroup.trim() });
+  }
+  return await q;
+}
+
+// src/tasks/taskLogs.ts
+function getLogsState(context) {
+  const holder = context;
+  if (holder.__tasksLogsState) return holder.__tasksLogsState;
+  const basePath = holder.params?.get?.("tasksLogsBasePath") || "./data";
+  const namespace = holder.params?.get?.("tasksLogsNamespace") || "tasks-logs";
+  const tableName = holder.params?.get?.("tasksLogsTable") || "runner";
+  const errorTableName = holder.params?.get?.("tasksErrorLogsTable") || `${tableName}-errors`;
+  const maxVersionsRaw = Number(holder.params?.get?.("tasksLogsMaxVersions"));
+  const pageSizeRaw = Number(holder.params?.get?.("tasksLogsPageSize"));
+  const errorDb = new FileDatabase({
+    basePath,
+    namespace,
+    tableName: errorTableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: Number.isFinite(maxVersionsRaw) && maxVersionsRaw > 0 ? maxVersionsRaw : 20,
+    pageSize: Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 2e3,
+    logger: holder.logger
+  });
+  const enabledRaw = holder.params?.get?.("tasksLogsEnabled");
+  const enabled = enabledRaw === void 0 ? true : !!enabledRaw;
+  if (!enabled) {
+    const disabledState = {
+      db: null,
+      errorDb,
+      queue: Promise.resolve(),
+      initialized: true,
+      errorInitialized: false
+    };
+    holder.__tasksLogsState = disabledState;
+    return disabledState;
+  }
+  const db = new FileDatabase({
+    basePath,
+    namespace,
+    tableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: Number.isFinite(maxVersionsRaw) && maxVersionsRaw > 0 ? maxVersionsRaw : 20,
+    pageSize: Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 2e3,
+    logger: holder.logger
+  });
+  const state = {
+    db,
+    errorDb,
+    queue: Promise.resolve(),
+    initialized: false,
+    errorInitialized: false
+  };
+  holder.__tasksLogsState = state;
+  return state;
+}
+function 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,
+    source: typeof params.source === "string" ? params.source : null,
+    resource: typeof params.resource === "string" ? params.resource : null,
+    payload
+  };
+}
+function appendTaskIpcLog(context, task, payload) {
+  const state = getLogsState(context);
+  if (!state.db && !state.errorDb) return;
+  const record = buildLogRecord(task, payload);
+  state.queue = state.queue.then(async () => {
+    if (state.db) {
+      await state.db.write([record], { forceNewVersion: !state.initialized });
+      state.initialized = true;
+    }
+    if (state.errorDb && isErrorPayload(payload)) {
+      await state.errorDb.write([record], { forceNewVersion: !state.errorInitialized });
+      state.errorInitialized = true;
+    }
+  }).catch((error) => {
+    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);
+    }
+    current = current.replace(raw, values.join(","));
+  }
+  return current;
+}
+function resolveSteps(field) {
+  const match = /^(.+)\/(\d+)$/.exec(field);
+  if (!match) return field;
+  const base = match[1];
+  const step = Number(match[2]);
+  if (!Number.isFinite(step) || step <= 0) return field;
+  return base.split(",").map((v) => Number(v)).filter((v) => Number.isFinite(v) && v % step === 0).join(",");
+}
+function convertPattern(pattern) {
+  const parts = pattern.trim().split(/\s+/);
+  if (parts.length !== 6) {
+    throw new Error(`Invalid schedule "${pattern}". Expected 6 fields: sec min hour day month weekday`);
+  }
+  return parts.map((field, idx) => resolveAsterisks(field, RANGES[idx])).map((field) => resolveRanges(field)).map((field) => resolveSteps(field));
+}
+function fieldMatches(field, value) {
+  const allowed = field.split(",").map((v) => Number(v));
+  return allowed.includes(value);
+}
+function timeMatcher(pattern, date = /* @__PURE__ */ new Date()) {
+  const parsed = convertPattern(pattern);
+  return fieldMatches(parsed[0], date.getSeconds()) && fieldMatches(parsed[1], date.getMinutes()) && fieldMatches(parsed[2], date.getHours()) && fieldMatches(parsed[3], date.getDate()) && fieldMatches(parsed[4], date.getMonth() + 1) && fieldMatches(parsed[5], date.getDay());
+}
+
+// src/tasks/TaskMaster.ts
+var TaskMaster = class {
+  context;
+  task;
+  constructor(context, task) {
+    this.context = context;
+    this.task = task;
+  }
+  cantRunReason() {
+    return false;
+  }
+  requestStop(_allowanceMs) {
+  }
+};
+
+// src/tasks/coreTasks/TaskPing.ts
+var TaskPing = class extends TaskMaster {
+  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;
+  requestStop(allowanceMs) {
+    this.stopRequested = true;
+    this.stopAllowanceMs = Number.isFinite(allowanceMs) && allowanceMs > 0 ? allowanceMs : 0;
+    this.context.logger.warn?.(
+      `[TaskSampleProcess] stop signal received (${this.task.id}), allowanceMs=${this.stopAllowanceMs}`
+    );
+  }
+  async run(reportProgress) {
+    const totalRaw = this.task?.params?.total ?? 10;
+    const delayRaw = this.task?.params?.delay ?? 1e3;
+    const nameRaw = this.task?.params?.name;
+    const total = Number(totalRaw);
+    const delay = Number(delayRaw);
+    const name = typeof nameRaw === "string" && nameRaw.trim() ? nameRaw.trim() : "sampleProcess";
+    const errors = [];
+    if (!Number.isInteger(total) || total <= 0) {
+      errors.push('param "total" must be a positive integer');
+    }
+    if (!Number.isInteger(delay) || delay < 0) {
+      errors.push('param "delay" must be an integer >= 0');
+    }
+    if (errors.length > 0) {
+      return {
+        success: false,
+        results: {
+          error: `Validation failed: ${errors.join(", ")}`,
+          received: { total: totalRaw, delay: delayRaw, name: nameRaw }
+        }
+      };
+    }
+    const startedAt = Date.now();
+    for (let i = 1; i <= total; i += 1) {
+      if (this.stopRequested) {
+        const remainingMs = Math.max(0, (total - i + 1) * delay);
+        if (remainingMs <= this.stopAllowanceMs) {
+          if (!this.stopDecisionLogged) {
+            this.stopDecisionLogged = true;
+            this.context.logger.warn?.(
+              `[TaskSampleProcess] continue to finish (${this.task.id}): remainingMs=${remainingMs} <= allowanceMs=${this.stopAllowanceMs}`
+            );
+          }
+        } else {
+          this.context.logger.warn?.(
+            `[TaskSampleProcess] stopping gracefully at iteration ${i}/${total} (${this.task.id}), remainingMs=${remainingMs} > allowanceMs=${this.stopAllowanceMs}`
+          );
+          return {
+            success: false,
+            results: {
+              message: `Stopped before completion at iteration ${i}/${total}`,
+              completed: i - 1,
+              total,
+              name,
+              remainingMs,
+              allowanceMs: this.stopAllowanceMs
+            }
+          };
+        }
+      }
+      const elapsed = Date.now() - startedAt;
+      const remaining = Math.max(0, (total - i) * delay);
+      const progress = {
+        name,
+        count: i,
+        total,
+        elapsedMs: elapsed,
+        remainingMs: remaining,
+        status: `running ${name}: ${i}/${total}`
+      };
+      this.context.logger.progress("running", {
+        prefix: name,
+        count: i,
+        total
+      });
+      await reportProgress(progress);
+      await sleepMs(delay);
+    }
+    return {
+      success: true,
+      results: {
+        message: `Completed ${total} iterations`,
+        total,
+        delay,
+        name
+      }
+    };
+  }
+};
+
+// src/tasks/coreTasks/TaskShellCommand.ts
+import { spawn } from "child_process";
+function runShellCommand(command, cwd) {
+  return new Promise((resolve2, reject) => {
+    const child = spawn(command, {
+      shell: true,
+      cwd: cwd || process.cwd(),
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let output = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      output += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      reject(error);
+    });
+    child.on("close", (exitCode, signal) => {
+      resolve2({
+        exitCode,
+        output: output.trim(),
+        stderr: stderr.trim(),
+        signal
+      });
+    });
+  });
+}
+var TaskShellCommand = class extends TaskMaster {
+  async run() {
+    const params = this.task?.params;
+    const commandRaw = typeof params === "string" ? params : params?.command;
+    const cwdRaw = typeof params === "string" ? void 0 : params?.cwd;
+    const command = typeof commandRaw === "string" ? commandRaw.trim() : "";
+    const cwd = typeof cwdRaw === "string" && cwdRaw.trim() ? cwdRaw.trim() : void 0;
+    if (!command) {
+      return {
+        success: false,
+        results: {
+          error: 'Validation failed: param "command" must be a non-empty string',
+          received: this.task?.params ?? null
+        }
+      };
+    }
+    try {
+      const result = await runShellCommand(command, cwd);
+      const success = result.exitCode === 0;
+      this.context.logger.info?.(
+        `[TaskShellCommand] command="${command}" exitCode=${String(result.exitCode)} (${this.task.id})`
+      );
+      return {
+        success,
+        results: {
+          command,
+          cwd: cwd ?? process.cwd(),
+          output: result.output,
+          stderr: result.stderr,
+          exitCode: result.exitCode,
+          signal: result.signal
+        }
+      };
+    } catch (error) {
+      return {
+        success: false,
+        results: {
+          command,
+          cwd: cwd ?? process.cwd(),
+          output: "",
+          stderr: "",
+          exitCode: null,
+          error: error?.message ?? String(error)
+        }
+      };
+    }
+  }
+};
+
+// src/tasks/coreTasks/TaskSystemInfo.ts
+import os2 from "os";
+import fs4 from "fs/promises";
+function toGb(valueBytes) {
+  return `${(valueBytes / 1024 ** 3).toFixed(2)} GB`;
+}
+function toMb(valueBytes) {
+  return `${(valueBytes / 1024 ** 2).toFixed(2)} MB`;
+}
+async function getDiskStats() {
+  const stats = await fs4.statfs("/");
+  const total = Number(stats.bsize) * Number(stats.blocks);
+  const free = Number(stats.bsize) * Number(stats.bavail);
+  const used = total - free;
+  return {
+    total: toGb(total),
+    used: toGb(used),
+    free: toGb(free)
+  };
+}
+var TaskSystemInfo = class extends TaskMaster {
+  async run() {
+    try {
+      const totalMemory = os2.totalmem();
+      const freeMemory = os2.freemem();
+      const usedMemory = totalMemory - freeMemory;
+      const cpus = os2.cpus();
+      const cpuUtilization = cpus.map((cpu) => {
+        const total = Object.values(cpu.times).reduce((acc, time) => acc + time, 0);
+        const usage = (total - cpu.times.idle) / total * 100;
+        return Number(usage.toFixed(2));
+      });
+      const processMemory = process.memoryUsage();
+      const disk = await getDiskStats();
+      const results = {
+        memory: {
+          total: toGb(totalMemory),
+          used: toGb(usedMemory),
+          free: toGb(freeMemory)
+        },
+        processMemory: {
+          rss: toMb(processMemory.rss),
+          heapTotal: toMb(processMemory.heapTotal),
+          heapUsed: toMb(processMemory.heapUsed),
+          external: toMb(processMemory.external)
+        },
+        disk,
+        cpu: {
+          cores: cpuUtilization.length,
+          utilization: cpuUtilization
+        },
+        runtime: {
+          platform: os2.platform(),
+          arch: os2.arch(),
+          uptimeSec: os2.uptime(),
+          hostname: os2.hostname()
+        }
+      };
+      this.context.logger.info?.(`[TaskSystemInfo] collected system metrics (${this.task.id})`);
+      return { success: true, results };
+    } catch (error) {
+      return {
+        success: false,
+        results: {
+          error: "Can't collect system stats",
+          message: error?.message ?? String(error)
+        }
+      };
+    }
+  }
+};
+
+// src/tasks/coreTasks/TaskSumAB.ts
+var TaskSumAB = class extends TaskMaster {
+  async run() {
+    const a = this.task?.params?.a;
+    const b = this.task?.params?.b;
+    if (typeof a !== "number" || Number.isNaN(a)) {
+      return {
+        success: false,
+        results: {
+          error: 'Validation failed: param "a" must be a valid number',
+          received: { a, b }
+        }
+      };
+    }
+    if (typeof b !== "number" || Number.isNaN(b)) {
+      return {
+        success: false,
+        results: {
+          error: 'Validation failed: param "b" must be a valid number',
+          received: { a, b }
+        }
+      };
+    }
+    const sum = a + b;
+    this.context.logger.info?.(`[TaskSumAB] ${a} + ${b} = ${sum} (${this.task.id})`);
+    return {
+      success: true,
+      results: { a, b, sum }
+    };
+  }
+};
+
+// src/tasks/coreTasks/TaskStopRunner.ts
+var TaskStopRunner = class extends TaskMaster {
+  async run() {
+    const allowanceMs = Number(this.task?.params?.allowanceMs ?? 5e3);
+    this.context.logger.warn?.(`[TaskStopRunner] stop requested (allowanceMs=${allowanceMs})`);
+    return {
+      success: true,
+      results: {
+        stopRunner: true,
+        allowanceMs,
+        message: "Runner stop requested"
+      }
+    };
+  }
+};
+
+// src/tasks/TasksRegistry.ts
+var TasksRegistry = class _TasksRegistry {
+  map = {};
+  constructor(initial) {
+    if (initial) {
+      this.addMany(initial);
+    }
+  }
+  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);
+  }
+  add(taskName, taskClass) {
+    this.map[taskName] = taskClass;
+    return this;
+  }
+  addMany(entries) {
+    for (const [name, klass] of Object.entries(entries)) {
+      this.add(name, klass);
+    }
+    return this;
+  }
+  get(taskName) {
+    return this.map[taskName];
+  }
+  listSupportedTasks() {
+    return Object.keys(this.map).sort();
+  }
+  toObject() {
+    return { ...this.map };
+  }
+};
+
+// src/tasks/taskScriptRunner.ts
+import { spawn as spawn2 } from "child_process";
+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}` : ""}`;
+}
+async function runNodeTaskScript(context, options) {
+  const cliArgs = toCliArgs(["--route=ipc", "--mode=json", ...options.args || []]);
+  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 || ""
+      }
+    }
+  );
+  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)}`
+        );
+      });
+    }
+  };
+  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 "";
+  };
+  child.stdout.on("data", (chunk) => {
+    const text = String(chunk);
+    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) => {
+    const text = String(chunk);
+    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;
+      return;
+    }
+    if (message && typeof message === "object") {
+      const level = typeof message.level === "string" ? message.level.toLowerCase() : "";
+      if (level === "error" || level === "fatal") {
+        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}`);
+      }
+    }
+  });
+  return await new Promise((resolve2, reject) => {
+    child.on("error", (error) => reject(error));
+    child.on("close", (exitCode, signal) => {
+      Promise.allSettled([progressWriteChain, progressCallbackChain]).finally(() => {
+        resolve2({
+          exitCode,
+          signal,
+          stdout: stdout.trim(),
+          stderr: stderr.trim(),
+          workerResult,
+          hadErrorMessage
+        });
+      });
+    });
+  });
+}
+
+// src/tasks/index.ts
+var LOCKED_BY_ERROR_MESSAGE = "locked by error";
+var defaultTasksRegistry = TasksRegistry.withCoreTasks();
+function getDb3(context) {
+  const db = context.db;
+  if (!db) {
+    throw new Error("Tasks component requires context.db. Initialize DB first and attach to context.");
+  }
+  return db;
+}
+function normalizeRegistry(registry) {
+  if (!registry) return defaultTasksRegistry;
+  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) {
+  return enqueueTask(context, {
+    queue,
+    target,
+    task: "stopRunner",
+    params: { allowanceMs },
+    priority: 1e6
+  });
+}
+async function signalRunningTasksStop(context, runningTaskInstances, allowanceMs) {
+  context.logger.warn?.(`[tasks] signaling ${runningTaskInstances.size} running task(s) to stop`);
+  for (const [, taskInstance] of runningTaskInstances) {
+    if (typeof taskInstance.requestStop === "function") {
+      try {
+        await taskInstance.requestStop(allowanceMs);
+      } catch (error) {
+        context.logger.warn?.("[tasks] task requestStop failed:", error);
+      }
+    }
+  }
+  context.emitter.emit("stop", allowanceMs);
+}
+async function executeClaimedTask(context, tasksTable, historyTable, row, registry, runningTaskInstances) {
+  const db = getDb3(context);
+  const taskName = row.task;
+  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)
+    });
+    if (row.schedule) {
+      await db(tasksTable).where({ id: row.id }).update({
+        started_at: null,
+        completed_at: /* @__PURE__ */ new Date(),
+        success: false,
+        results: toJsonColumn(err),
+        past_due: null,
+        paused_at: db.fn.now(),
+        progress: LOCKED_BY_ERROR_MESSAGE
+      });
+    } else {
+      await db(tasksTable).where({ id: row.id }).delete();
+    }
+    return { stopRunnerRequested: false, stopAllowanceMs: 0 };
+  }
+  let success = false;
+  let results = null;
+  let taskInstance = null;
+  try {
+    taskInstance = new TaskClass(context, row);
+    runningTaskInstances.set(row.id, taskInstance);
+    const runResult = await taskInstance.run((progress) => updateTaskProgress(context, tasksTable, row.id, progress));
+    success = !!runResult?.success;
+    results = runResult?.results ?? null;
+  } catch (error) {
+    success = false;
+    results = {
+      message: error?.message ?? String(error),
+      name: error?.name ?? "Error",
+      stack: error?.stack ?? null
+    };
+  } finally {
+    runningTaskInstances.delete(row.id);
+  }
+  await db(historyTable).insert({
+    ...rowForHistory,
+    completed_at: /* @__PURE__ */ new Date(),
+    success,
+    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");
+    const fallbackRecoverCommand = [
+      "npx",
+      "tsx",
+      "examples/tasks/recover-task.ts",
+      `--dbName='${dbName.replace(/'/g, `'\\''`)}'`,
+      `--table='${tableName.replace(/'/g, `'\\''`)}'`,
+      `--id='${String(row.id).replace(/'/g, `'\\''`)}'`
+    ].join(" ");
+    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}`,
+      details: results
+    });
+  }
+  if (row.schedule) {
+    if (success) {
+      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
+      });
+    } else {
+      await db(tasksTable).where({ id: row.id }).update({
+        started_at: null,
+        completed_at: /* @__PURE__ */ new Date(),
+        success,
+        results: toJsonColumn(results),
+        paused_at: db.fn.now(),
+        progress: LOCKED_BY_ERROR_MESSAGE,
+        past_due: null
+      });
+    }
+  } else {
+    await db(tasksTable).where({ id: row.id }).delete();
+  }
+  const stopRunnerRequested = !!(results && typeof results === "object" && results.stopRunner === true);
+  const stopAllowanceMs = stopRunnerRequested ? Number(results.allowanceMs ?? 5e3) : 0;
+  return { stopRunnerRequested, stopAllowanceMs };
+}
+async function claimNextRunnableTask(context, tasksTable, target, registry, scanLimit, taskNames) {
+  const db = getDb3(context);
+  let query = db(tasksTable).whereNull("started_at").whereNull("paused_at").where({ target }).orderByRaw("CASE WHEN past_due IS NULL THEN 1 ELSE 0 END ASC").orderBy([{ column: "priority", order: "desc" }]).orderByRaw("CASE WHEN completed_at IS NULL THEN 0 ELSE 1 END ASC").orderBy([{ column: "completed_at", order: "asc" }, { column: "created_at", order: "asc" }]).limit(scanLimit);
+  if (taskNames && taskNames.length > 0) {
+    query = query.whereIn("task", taskNames);
+  }
+  const candidates = await query;
+  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 updated = await db(tasksTable).where({ id: row.id }).whereNull("started_at").whereNull("paused_at").update({ started_at: db.fn.now() }).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 target = options.target;
+  const pollMs = options.pollMs ?? 1e3;
+  const maxParallel = options.maxParallel ?? 1;
+  const scanLimit = options.scanLimit ?? 100;
+  const allowedTasks = normalizeAllowedTasks(options.allowedTasks);
+  const registry = normalizeRegistry(options.registry);
+  const { tasksTable, historyTable } = queueToTableNames(queue);
+  if (!target) throw new Error("runTasksLoop: target is required");
+  const runningPromises = /* @__PURE__ */ new Set();
+  const runningTaskInstances = /* @__PURE__ */ new Map();
+  let runningStopControlPromise = null;
+  let stopRequested = false;
+  let stopAllowanceMs = 5e3;
+  context.__tasksRunnerStop = false;
+  let registryReg = null;
+  let registryInterval = null;
+  const hbGroup = options.runnerServiceGroup?.trim();
+  if (hbGroup) {
+    const identityDir = options.runnerIdentityDir ?? "./data/runner-identities";
+    const hbIntervalMs = options.runnerHeartbeatIntervalMs ?? 1e4;
+    const staleMs = options.runnerHeartbeatStaleMs ?? 45e3;
+    const defaultMeta = {
+      component: "tasks-runner",
+      allowedTasks: allowedTasks?.length ? allowedTasks.join(",") : "all"
+    };
+    registryReg = await registerInServicesRegistry(context, {
+      queue,
+      target,
+      serviceGroup: hbGroup,
+      serviceName: options.runnerServiceName,
+      identityDir,
+      staleMs,
+      groupMaxInstances: options.runnerGroupMaxInstances,
+      enforceMaxInstances: options.runnerEnforceMaxInstances ?? true,
+      metadata: options.runnerMetadata ?? defaultMeta
+    });
+    registryInterval = setInterval(() => {
+      void touchServicesRegistry(context, registryReg).catch((err) => {
+        context.logger.warn?.(`[services-registry] touch failed: ${err?.message ?? String(err)}`);
+      });
+    }, hbIntervalMs);
+  }
+  try {
+    while (!context.isStop() && !stopRequested && !context.__tasksRunnerStop) {
+      if (!runningStopControlPromise) {
+        const claimedStopTask = await claimNextRunnableTask(
+          context,
+          tasksTable,
+          target,
+          registry,
+          10,
+          ["stopRunner", "stop"]
+        );
+        if (claimedStopTask) {
+          runningStopControlPromise = executeClaimedTask(
+            context,
+            tasksTable,
+            historyTable,
+            claimedStopTask,
+            registry,
+            runningTaskInstances
+          ).then(async (outcome) => {
+            if (outcome.stopRunnerRequested && !stopRequested) {
+              stopRequested = true;
+              stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
+              context.__tasksRunnerStop = true;
+              await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
+            }
+          }).finally(() => {
+            runningStopControlPromise = null;
+          });
+        }
+      }
+      while (runningPromises.size < maxParallel) {
+        const claimed = await claimNextRunnableTask(
+          context,
+          tasksTable,
+          target,
+          registry,
+          scanLimit,
+          allowedTasks
+        );
+        if (!claimed) break;
+        const p = executeClaimedTask(context, tasksTable, historyTable, claimed, registry, runningTaskInstances).then(async (outcome) => {
+          if (outcome.stopRunnerRequested && !stopRequested) {
+            stopRequested = true;
+            stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
+            context.__tasksRunnerStop = true;
+            await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
+          }
+        }).finally(() => {
+          runningPromises.delete(p);
+        });
+        runningPromises.add(p);
+      }
+      await sleepMs(pollMs);
+    }
+    if (context.isStop() && !stopRequested) {
+      await signalRunningTasksStop(context, runningTaskInstances, 5e3);
+    }
+    if (runningPromises.size > 0) {
+      if (stopRequested) {
+        await Promise.race([
+          Promise.allSettled(Array.from(runningPromises)),
+          sleepMs(stopAllowanceMs).then(() => {
+            context.logger.warn?.(
+              `[tasks] stop allowance (${stopAllowanceMs}ms) reached; ${runningPromises.size} task(s) still running`
+            );
+          })
+        ]);
+      } else {
+        await Promise.allSettled(Array.from(runningPromises));
+      }
+    }
+  } finally {
+    if (registryInterval) {
+      clearInterval(registryInterval);
+      registryInterval = null;
+    }
+    if (registryReg) {
+      await unregisterServicesRegistry(context, registryReg).catch((err) => {
+        context.logger.warn?.(`[services-registry] unregister failed: ${err?.message ?? String(err)}`);
+      });
+      registryReg = null;
+      delete context.servicesRegistry;
+      delete context.runnerHeartbeat;
+    }
+  }
+}
+async function waitForTaskResult(context, taskId, options = {}) {
+  const db = getDb3(context);
+  const queue = options.queue ?? "tasks";
+  const timeoutMs = options.timeoutMs ?? 6e4;
+  const pollMs = options.pollMs ?? 500;
+  const { tasksTable, historyTable } = queueToTableNames(queue);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    const done = await db(historyTable).where({ id: taskId }).orderBy("created_at", "desc").first();
+    if (done) return done;
+    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;
+    }
+    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;
+  constructor(context, options = {}) {
+    this.context = context;
+    this.queue = options.queue ?? "tasks";
+    this.target = options.target ?? "localRunner";
+    this.recreateTaskTables = options.recreateTaskTables ?? false;
+    this.pollMs = options.pollMs ?? 1e3;
+    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.runnerHeartbeatIntervalMs = options.runnerHeartbeatIntervalMs;
+    this.runnerHeartbeatStaleMs = options.runnerHeartbeatStaleMs;
+    this.runnerGroupMaxInstances = options.runnerGroupMaxInstances;
+    this.runnerEnforceMaxInstances = options.runnerEnforceMaxInstances;
+    this.runnerMetadata = options.runnerMetadata;
+  }
+  static init(context, options = {}) {
+    const defs = {
+      table: "string default tasks",
+      target: "string default localRunner",
+      recreateTaskTables: "boolean default false",
+      pollMs: "number default 1000",
+      maxParallel: "number default 1",
+      scanLimit: "number default 100",
+      allowedTasks: "string",
+      runnerServiceGroup: "string",
+      runnerServiceName: "string",
+      runnerIdentityDir: "string default ./data/runner-identities",
+      runnerHeartbeatIntervalMs: "number default 10000",
+      runnerHeartbeatStaleMs: "number default 45000",
+      runnerGroupMaxInstances: "number",
+      runnerEnforceMaxInstances: "boolean default true"
+    };
+    const discovered = context.params.getAllForModule(defs);
+    const resolved = {
+      queue: discovered.table,
+      target: discovered.target,
+      recreateTaskTables: discovered.recreateTaskTables,
+      pollMs: discovered.pollMs,
+      maxParallel: discovered.maxParallel,
+      scanLimit: discovered.scanLimit,
+      allowedTasks: discovered.allowedTasks,
+      runnerServiceGroup: discovered.runnerServiceGroup,
+      runnerServiceName: discovered.runnerServiceName,
+      runnerIdentityDir: discovered.runnerIdentityDir,
+      runnerHeartbeatIntervalMs: discovered.runnerHeartbeatIntervalMs,
+      runnerHeartbeatStaleMs: discovered.runnerHeartbeatStaleMs,
+      runnerGroupMaxInstances: discovered.runnerGroupMaxInstances,
+      runnerEnforceMaxInstances: discovered.runnerEnforceMaxInstances,
+      ...options
+    };
+    return new _TasksManager(context, resolved);
+  }
+  async ensureTaskTables(options = {}) {
+    await ensureTaskTables(this.context, {
+      queue: this.queue,
+      recreate: options.recreate ?? this.recreateTaskTables
+    });
+  }
+  async runTasksLoop(options = {}) {
+    await runTasksLoop(this.context, {
+      queue: options.queue ?? this.queue,
+      target: options.target ?? this.target,
+      pollMs: options.pollMs ?? this.pollMs,
+      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,
+      runnerHeartbeatIntervalMs: options.runnerHeartbeatIntervalMs ?? this.runnerHeartbeatIntervalMs,
+      runnerHeartbeatStaleMs: options.runnerHeartbeatStaleMs ?? this.runnerHeartbeatStaleMs,
+      runnerGroupMaxInstances: options.runnerGroupMaxInstances ?? this.runnerGroupMaxInstances,
+      runnerEnforceMaxInstances: options.runnerEnforceMaxInstances ?? this.runnerEnforceMaxInstances,
+      runnerMetadata: options.runnerMetadata ?? this.runnerMetadata
+    });
+  }
+};
 export {
   Args,
   Box5 as Box,
@@ -3919,8 +5468,18 @@ export {
   ScreenFooter,
   ScreenRow,
   ScreenTitle,
+  TaskMaster,
+  TaskPing,
+  TaskSampleProcess,
+  TaskShellCommand,
+  TaskStopRunner,
+  TaskSumAB,
+  TaskSystemInfo,
+  TasksManager,
+  TasksRegistry,
   Text5 as Text,
   TextBlock,
+  appendTaskIpcLog,
   buildBreadcrumb,
   buildDetailBreadcrumb,
   buildFooter,
@@ -3928,15 +5487,28 @@ export {
   dbFindAndConnect,
   dbInit,
   defaultFileSynopsisFunction,
+  defaultTasksRegistry,
   defaultVersionSynopsisFunction,
+  enqueueStopTask,
+  enqueueTask,
+  ensureTaskTables,
   getArgsInstance,
   createElement2 as h,
   joiEdateType,
   joiStringArrayType,
+  listServicesRegistry as listAliveRunnerHeartbeats,
+  listServicesRegistry,
   listSources,
   listTables,
   load,
   organizeFooterMessages,
+  queueToTableNames,
+  registerInServicesRegistry,
+  registerInServicesRegistry as registerRunnerHeartbeat,
+  runNodeTaskScript,
+  runTasksLoop,
+  servicesRegistryTable as runnerHeartbeatsTable,
+  servicesRegistryTable,
   setupContext,
   showListScreen,
   showMenuScreen,
@@ -3944,11 +5516,18 @@ export {
   showMultiColumnListWithPreviewScreen,
   showScreen,
   showWordGridScreen,
+  touchServicesRegistry as touchRunnerHeartbeat,
+  touchServicesRegistry,
+  unregisterServicesRegistry as unregisterRunnerHeartbeat,
+  unregisterServicesRegistry,
+  updateServicesRegistryMetadata,
+  updateTaskProgress,
   useCallback,
   useEffect3 as useEffect,
   useInput2 as useInput,
   useMemo,
   useRef3 as useRef,
-  useState3 as useState
+  useState3 as useState,
+  waitForTaskResult
 };
 //# sourceMappingURL=index.js.map