@faapi/faapi 6.32.0 → 6.34.0

package/dist/cli/index.js

@@ -767,38 +767,30 @@ function setCachedMiddlewares(absPath, bundle) {
   middlewareCache.set(absPath, bundle);
 }
 async function loadMiddlewaresFile(filePath) {
-  let module;
-  try {
-    module = await importWithCacheBust(filePath);
-  } catch (err) {
-    console.error(
-      `[faapi] Failed to load middlewares from ${filePath}:`,
-      err instanceof Error ? err.stack ?? err.message : err
-    );
-    return { middlewares: [], injectors: {} };
-  }
+  const module = await importWithCacheBust(filePath);
   const middlewares = module.default ?? module.middlewares ?? [];
   if (!Array.isArray(middlewares)) {
-    console.warn(`[faapi] middlewares.ts \u5E94\u5BFC\u51FA\u6570\u7EC4\uFF0C\u5DF2\u5FFD\u7565: ${filePath}`);
-    return { middlewares: [], injectors: {} };
+    throw new TypeError(
+      `[faapi] middlewares.ts must export an array (default or named "middlewares"): ${filePath}`
+    );
   }
-  const validMiddlewares = middlewares.filter((m) => {
+  const validMiddlewares = [];
+  for (const m of middlewares) {
     if (typeof m !== "function") {
-      console.warn(`[faapi] \u65E0\u6548\u7684\u4E2D\u95F4\u4EF6\u9879\uFF08\u5E94\u4E3A\u51FD\u6570\uFF09\uFF0C\u5DF2\u5FFD\u7565: ${typeof m}`);
-      return false;
+      throw new TypeError(
+        `[faapi] every middleware must be a function, got ${typeof m}: ${filePath}`
+      );
     }
-    return true;
-  });
+    validMiddlewares.push(m);
+  }
   const injectors = module.injectors ?? {};
   if (typeof injectors !== "object" || injectors === null) {
-    console.warn(`[faapi] injectors \u5E94\u5BFC\u51FA\u5BF9\u8C61\uFF0C\u5DF2\u5FFD\u7565: ${filePath}`);
-    return { middlewares: validMiddlewares, injectors: {} };
+    throw new TypeError(`[faapi] "injectors" export must be an object: ${filePath}`);
   }
   const validInjectors = {};
   for (const [name, injector] of Object.entries(injectors)) {
     if (typeof injector !== "function") {
-      console.warn(`[faapi] \u6CE8\u5165\u5668 ${name} \u5E94\u4E3A\u51FD\u6570\uFF0C\u5DF2\u5FFD\u7565`);
-      continue;
+      throw new TypeError(`[faapi] injector "${name}" must be a function: ${filePath}`);
     }
     validInjectors[name] = injector;
   }
@@ -813,10 +805,16 @@ async function loadMergedMiddlewares(middlewarePaths) {
     if (bundle === void 0) {
       let loading = inFlight.get(absMwPath);
       if (!loading) {
-        loading = loadMiddlewaresFile(absMwPath).then((result) => {
-          setCachedMiddlewares(absMwPath, result);
-          return result;
-        });
+        loading = loadMiddlewaresFile(absMwPath).then(
+          (result) => {
+            setCachedMiddlewares(absMwPath, result);
+            return result;
+          },
+          (err) => {
+            inFlight.delete(absMwPath);
+            throw err;
+          }
+        );
         inFlight.set(absMwPath, loading);
       }
       bundle = await loading;
@@ -3629,25 +3627,27 @@ function detectIgnoredMetaFields(source, strictHit) {
   for (const line of source.split("\n")) {
     const trimmed = line.trim();
     if (trimmed.startsWith("//")) continue;
+    if (trimmed.startsWith("*") || trimmed.startsWith("/*") || trimmed.endsWith("*/")) continue;
     for (const field of ALL_META_FIELDS) {
       if (new RegExp(`\\b${field}\\s*:`).test(trimmed)) declared.add(field);
     }
   }
   return ALL_META_FIELDS.filter((field) => declared.has(field) && !strictHit[field]);
 }
-function warnIgnoredMetaFields(name, fields) {
-  for (const field of fields) {
+function throwIgnoredMetaFields(name, fields) {
+  if (fields.length === 0) return;
+  const details = fields.map((field) => {
     if (STRING_META_FIELDS.includes(field)) {
-      console.warn(
-        `[faapi] Task "${name}" declares "${field}" but its value is not a string literal \u2014 the declaration was ignored and the task will not be cron-scheduled. Meta values are extracted from source code without importing it, so only literal values are recognized: use a quoted literal (cron: '0 3 * * *'), not an expression or a dynamic value.`
-      );
-    } else {
-      const consequence = field === "timeoutMs" ? " and the task will run in-process with no timeout" : "";
-      console.warn(
-        `[faapi] Task "${name}" declares "${field}" but its value is not a numeric literal \u2014 the declaration was ignored${consequence}. Meta values are extracted from source code without importing it, so only literal values are recognized (underscores allowed, e.g. 1_800_000); expressions like 30 * 60_000 or dynamic values are not supported.`
-      );
+      return `"${field}": value is not a string literal \u2014 the declaration would be ignored and the task would not be cron-scheduled. Use a quoted literal (cron: '0 3 * * *'), not an expression or a dynamic value.`;
     }
-  }
+    const consequence = field === "timeoutMs" ? " \u2014 the declaration would be ignored and the task would silently run in-process with no timeout" : " \u2014 the declaration would be ignored";
+    return `"${field}": value is not a numeric literal${consequence}. Only literal values are recognized (underscores allowed, e.g. 1_800_000); expressions like 30 * 60_000 or dynamic values are not supported.`;
+  });
+  throw new Error(
+    `[faapi] Task "${name}" declares meta field(s) with non-literal values:
+  ${details.join("\n  ")}
+Meta values are extracted from source code without importing it, so only literals are recognized. If a matched line is inside a block comment (e.g. a single-line /* ... */ comment containing a meta-like declaration), rewrite the comment so it does not look like a meta declaration.`
+  );
 }
 function parseNumericLiteral(raw) {
   return Number(raw.replace(/_/g, ""));
@@ -3715,7 +3715,7 @@ async function scanTasks(rootDir, patterns) {
       timeoutMs: timeoutMs !== void 0,
       graceMs: graceMs !== void 0
     };
-    warnIgnoredMetaFields(name, detectIgnoredMetaFields(source, strictHit));
+    throwIgnoredMetaFields(name, detectIgnoredMetaFields(source, strictHit));
     tasks.push(manifest);
   }
   return tasks.sort((a, b) => a.name.localeCompare(b.name));
@@ -3830,6 +3830,7 @@ function generateTaskSchemaFileSource(sources, resolveType, helpersImportPath) {
 }
 async function generateTaskArtifacts(manifests, rootDir, dist) {
   const metadata = [];
+  const declarationErrors = [];
   if (manifests.length > 0) {
     const programByFile = createPrograms(manifests.map((m) => path17.resolve(rootDir, m.filePath)));
     for (const manifest of manifests) {
@@ -3838,11 +3839,28 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
         name: manifest.name,
         filePath: manifest.filePath
       });
-      if (result) {
-        metadata.push({ ...result, taskName: manifest.name });
+      if (!result) {
+        declarationErrors.push(
+          `"${manifest.name}" (${manifest.filePath}): no exported run function found`
+        );
+        continue;
       }
+      if (!result.inputTypeName) {
+        declarationErrors.push(
+          `"${manifest.name}" (${manifest.filePath}): run's first parameter has no type name \u2014 declare a Payload type (an empty interface for parameterless tasks), or explicitly opt out of validation with "type Payload = unknown"`
+        );
+        continue;
+      }
+      metadata.push({ ...result, taskName: manifest.name });
     }
   }
+  if (declarationErrors.length > 0) {
+    throw new Error(
+      `[faapi] ${declarationErrors.length} task(s) missing a Payload type declaration \u2014 payload validation must not be silently skipped:
+  ${declarationErrors.join("\n  ")}
+Every task must declare a payload type on run's first parameter; "type Payload = unknown" generates an always-passing schema (explicit no-validation opt-out).`
+    );
+  }
   const serialized = serializeTasks(manifests, dist);
   const tasksPath = path17.resolve(rootDir, dist, TASKS_FILE);
   await writeTasksModule(serialized, tasksPath);
@@ -4023,11 +4041,7 @@ async function ensureMiddlewaresCompiled(middlewarePaths, rootDir) {
   if (!dist) return;
   for (const mwPath of middlewarePaths) {
     const sourcePath = prodPathToSourcePath(mwPath, rootDir, dist);
-    try {
-      await ensureCompiled(sourcePath, rootDir, dist);
-    } catch (err) {
-      console.error(`[faapi] Failed to compile middleware source ${sourcePath}:`, err);
-    }
+    await ensureCompiled(sourcePath, rootDir, dist);
   }
 }
 function prodSourcePathToProductPath(sourceAbsPath, rootDir, dist) {
@@ -6944,17 +6958,14 @@ function formatEntry(entry) {
     const plain = Object.fromEntries(
       Object.entries(entry.fields).map(([k, v]) => [k, serializeFieldValue(v)])
     );
-    try {
-      line += ` ${JSON.stringify(plain)}`;
-    } catch (err) {
-      line += ` [unserializable fields: ${err instanceof Error ? err.message : String(err)}]`;
-    }
+    line += ` ${stringifyJson(plain)}`;
   }
   return line;
 }
 var init_formatEntry = __esm({
   "src/logger/formatEntry.ts"() {
     "use strict";
+    init_stringifyJson();
   }
 });
 
@@ -6970,7 +6981,14 @@ function createFileLogSink(options) {
   };
   const openStream = (name) => {
     const stream = fs18.createWriteStream(path24.join(options.dir, `${name}.log`), { flags: "a" });
-    stream.on("error", () => {
+    let streamErrorLogged = false;
+    stream.on("error", (err) => {
+      if (streamErrorLogged) return;
+      streamErrorLogged = true;
+      console.error(
+        `[faapi] log file stream "${name}.log" failed \u2014 file logging on this stream stopped (subsequent errors suppressed). Check disk space / permissions for ${options.dir}:`,
+        err
+      );
     });
     streams.set(name, stream);
   };
@@ -9317,7 +9335,8 @@ async function sendErrorResponse(err, meta, res, onError, ctx) {
   if (onError && ctx) {
     try {
       await onError(err, ctx);
-    } catch {
+    } catch (hookErr) {
+      console.error("[faapi] lifecycle onError hook threw:", hookErr);
     }
   }
 }
@@ -9461,19 +9480,6 @@ function resolveWorkerEntryUrl() {
   workerEntryUrl = existsSync3(fileURLToPath(js)) ? js : new URL("./workerEntry.ts", import.meta.url);
   return workerEntryUrl;
 }
-function safeConfig(config) {
-  if (config === void 0 || config === null) return config;
-  try {
-    structuredClone(config);
-    return config;
-  } catch {
-  }
-  try {
-    return JSON.parse(JSON.stringify(config));
-  } catch {
-    return void 0;
-  }
-}
 function reviveError(payload) {
   const err = new Error(payload?.message ?? "task worker error");
   if (payload?.name !== void 0) err.name = payload.name;
@@ -9542,6 +9548,53 @@ async function runTaskInWorker(options) {
     worker.on(
       "message",
       (msg) => {
+        if (msg?.type === "tasks-call") {
+          const { seq, method, args } = msg;
+          const reply = (body) => {
+            try {
+              worker.postMessage({ type: "tasks-result", seq, ...body });
+            } catch (err) {
+              try {
+                worker.postMessage({
+                  type: "tasks-result",
+                  seq,
+                  ok: false,
+                  error: {
+                    name: "Error",
+                    message: `taskCtx.tasks.${method} result is not cloneable: ${String(err)}`,
+                    stack: void 0,
+                    props: {}
+                  }
+                });
+              } catch {
+              }
+            }
+          };
+          if (!options.onTasksCall) {
+            reply({
+              ok: false,
+              error: {
+                name: "Error",
+                message: `taskCtx.tasks.${method} is unavailable: no host handler was provided for this execution`,
+                stack: void 0,
+                props: {}
+              }
+            });
+            return;
+          }
+          options.onTasksCall(method, args ?? []).then((value) => reply({ ok: true, value })).catch((err) => {
+            reply({
+              ok: false,
+              error: {
+                name: err instanceof Error ? err.name : "Error",
+                message: err instanceof Error ? err.message : String(err),
+                stack: err instanceof Error ? err.stack : void 0,
+                props: {}
+              }
+            });
+          });
+          return;
+        }
         if (phase === "grace") {
           if (msg?.type === "done") {
             finish(
@@ -9588,7 +9641,6 @@ async function runTaskInWorker(options) {
         type: "run",
         payload,
         taskCtx: {
-          config: safeConfig(taskCtx.config),
           job: taskCtx.job
         },
         registries: options.registries,
@@ -9597,9 +9649,7 @@ async function runTaskInWorker(options) {
       });
     } catch (err) {
       finish(
-        () => reject(
-          new Error(`Task "${taskCtx.job.name}" payload/config is not cloneable: ${String(err)}`)
-        )
+        () => reject(new Error(`Task "${taskCtx.job.name}" payload is not cloneable: ${String(err)}`))
       );
     }
   });
@@ -9650,13 +9700,14 @@ function createTaskQueue(deps) {
   const loadTaskModule = deps.loadTaskModule ?? (async (filePath) => await import(filePath));
   const loadPayloadSchema = deps.loadPayloadSchema ?? (async (filePath) => {
     const zodPath = path28.join(path28.dirname(filePath), "zod.js");
-    try {
-      const mod = await import(zodPath);
-      const schemaKey = Object.keys(mod).find((k) => k.endsWith("Schema"));
-      return schemaKey ? mod[schemaKey] : void 0;
-    } catch {
-      return void 0;
+    const mod = await import(zodPath);
+    const schemaKey = Object.keys(mod).find((k) => k.endsWith("Schema"));
+    if (!schemaKey) {
+      throw new Error(
+        `[faapi] Task payload schema artifact has no *Schema export: ${zodPath} \u2014 re-run "faapi dev" / "faapi build" to regenerate task artifacts.`
+      );
     }
+    return mod[schemaKey];
   });
   function assertKnownTask(name) {
     const meta = registry.get(name);
@@ -9665,6 +9716,54 @@ function createTaskQueue(deps) {
       throw new Error(`[faapi] Unknown task "${name}". Registered tasks: ${known}`);
     }
   }
+  function assertGroupSupport() {
+    if (!driver.groups) {
+      throw new Error(
+        "[faapi] Task driver does not support group accounting (TaskDriver.groups is not implemented). Group enqueue/settle requires a driver that implements it \u2014 see driverTypes.md / taskGroups.md."
+      );
+    }
+  }
+  async function maybeFireCompletion(snap) {
+    if (!driver.groups) return;
+    if (!snap.onComplete || snap.completionEnqueued || snap.settled < snap.total) return;
+    const summary = {
+      groupId: snap.groupId,
+      task: snap.task,
+      total: snap.total,
+      done: snap.done,
+      failed: snap.failed,
+      cancelled: snap.cancelled,
+      settled: snap.settled
+    };
+    try {
+      await enqueueCore(snap.onComplete, summary, {
+        dedupId: GROUP_COMPLETION_DEDUP(snap.groupId)
+      });
+      await driver.groups.markCompletionEnqueued(snap.groupId);
+    } catch (err) {
+      console.error(
+        `[faapi] task group "${snap.groupId}" completion enqueue failed (group is settled; re-invoke enqueueGroup with the same groupId to re-arm the callback):`,
+        err
+      );
+    }
+  }
+  async function settleGroup(record, outcome, willRetry) {
+    const groupId = record.groupId;
+    if (!groupId || !driver.groups) return;
+    if (outcome !== "done" && willRetry) return;
+    try {
+      const snap = await driver.groups.settle(groupId, record.id, outcome);
+      if (outcome === "failed" && snap.onFailure === "fail-fast") {
+        await maybeFireCompletion(await driver.groups.cancelRemaining(groupId));
+      }
+      await maybeFireCompletion(snap);
+    } catch (err) {
+      console.error(
+        `[faapi] task group accounting failed for "${groupId}" (job ${record.id}, outcome ${outcome}):`,
+        err
+      );
+    }
+  }
   function snapshotRegistries() {
     return {
       agents: registriesView.agent.listAgents().map((core) => registriesView.agent.getAgentEntry(core.name)).filter((entry) => entry !== void 0),
@@ -9675,14 +9774,13 @@ function createTaskQueue(deps) {
   async function validatePayload(name, payload) {
     if (!schemaCache.has(name)) {
       const meta = registry.get(name);
-      schemaCache.set(
-        name,
-        await loadPayloadSchema(path28.resolve(rootDir, meta.filePath)).catch(() => void 0)
-      );
+      schemaCache.set(name, await loadPayloadSchema(path28.resolve(rootDir, meta.filePath)));
     }
     const schema = schemaCache.get(name);
     if (!schema || typeof schema.safeParse !== "function") {
-      return payload;
+      throw new Error(
+        `[faapi] Task "${name}" has no valid payload schema (zod.js missing or no *Schema export). Payload declarations are mandatory: re-run "faapi dev" / "faapi build" to regenerate task artifacts.`
+      );
     }
     const result = schema.safeParse(payload);
     if (!result.success) {
@@ -9704,11 +9802,13 @@ function createTaskQueue(deps) {
       attempts: 0,
       createdAt: Date.now()
     };
+    if (job.groupId !== void 0) record.groupId = job.groupId;
     record.attempts = job.attempt;
     transitionStatus(record, "running");
     delete record.progress;
     record.error = void 0;
     records.set(job.id, record);
+    const willRetry = job.attempt <= (meta.retries ?? 0);
     try {
       let result;
       if (meta.timeoutMs !== void 0 && meta.timeoutMs > 0) {
@@ -9716,7 +9816,8 @@ function createTaskQueue(deps) {
           taskModulePath: path28.resolve(rootDir, meta.filePath),
           payload: job.payload,
           taskCtx: {
-            config: deps.config,
+            // 隔离任务不传 config：worker 线程不接收进程配置（config 含函数字段
+            // 不可结构化克隆，框架不做降级传递）——任务数据经 payload 显式传入
             resourcesDir: deps.resourcesDir,
             job: { id: job.id, name: job.name, attempt: job.attempt }
           },
@@ -9737,7 +9838,16 @@ function createTaskQueue(deps) {
           onProgress: (value) => {
             if (record.status === "running") record.progress = value;
           },
-          onLog: writeLogEntry
+          onLog: writeLogEntry,
+          // 隔离路径的 taskCtx.tasks 为 postMessage RPC 代理——宿主侧按方法名
+          // 分派到队列本体（与 ctx.tasks / app.tasks 同一实例），结果/错误按 seq 回传
+          onTasksCall: async (method, args) => {
+            if (!TASK_CLIENT_METHODS.has(method)) {
+              throw new Error(`[faapi] Unknown task client method "${method}"`);
+            }
+            const fn = queue[method];
+            return fn.apply(queue, args);
+          }
         });
       } else {
         let mod = moduleCache2.get(job.name);
@@ -9750,6 +9860,8 @@ function createTaskQueue(deps) {
         }
         const taskCtx = {
           signal: job.signal,
+          // 活引用：与 ctx.tasks / app.tasks 同一 app 实例队列
+          tasks: queue,
           config: deps.config,
           job: { id: job.id, name: job.name, attempt: job.attempt },
           registries: registriesView,
@@ -9767,23 +9879,27 @@ function createTaskQueue(deps) {
       transitionStatus(record, "done");
       record.result = result;
       evictFinishedRecords();
+      await settleGroup(record, "done", willRetry);
       return result;
     } catch (err) {
       const cancelled = err instanceof TaskCancelledError || job.signal.aborted;
-      transitionStatus(record, cancelled ? "cancelled" : "failed");
+      const outcome = cancelled ? "cancelled" : "failed";
+      transitionStatus(record, outcome);
       record.error = err instanceof Error ? err.message : String(err);
       evictFinishedRecords();
+      await settleGroup(record, outcome, willRetry);
       if (deps.onFailed) {
         void Promise.resolve().then(
           () => deps.onFailed({
             task: job.name,
             jobId: job.id,
             attempt: job.attempt,
-            willRetry: job.attempt <= (meta.retries ?? 0),
+            willRetry,
             cancelled,
             error: record.error
           })
-        ).catch(() => {
+        ).catch((hookErr) => {
+          console.error(`[faapi] task onFailed hook threw for "${job.name}":`, hookErr);
         });
       }
       throw err;
@@ -9797,35 +9913,86 @@ function createTaskQueue(deps) {
       });
     }
   }
+  async function enqueueCore(name, payload, opts) {
+    if (stopped) {
+      throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
+    }
+    assertKnownTask(name);
+    const data = await validatePayload(name, payload);
+    const meta = registry.get(name);
+    const id = await driver.enqueue(name, data, {
+      delayMs: opts?.delayMs,
+      retries: meta.retries ?? 0,
+      dedupId: opts?.dedupId,
+      // 执行硬限预算透传驱动（pgboss 映射 expireInSeconds）：未声明 timeoutMs 时
+      // 两字段为 undefined，驱动用自身兜底
+      timeoutMs: meta.timeoutMs,
+      graceMs: meta.graceMs,
+      ...opts?.groupId !== void 0 ? { groupId: opts.groupId } : {}
+    });
+    if (!records.has(id)) {
+      records.set(id, {
+        id,
+        name,
+        payload: data,
+        status: "pending",
+        attempts: 0,
+        ...opts?.groupId !== void 0 ? { groupId: opts.groupId } : {},
+        createdAt: Date.now(),
+        ...opts?.delayMs ? { runAt: Date.now() + opts.delayMs } : {}
+      });
+    }
+    return id;
+  }
   const queue = {
     async enqueue(name, payload = {}, opts) {
+      const id = await enqueueCore(name, payload, {
+        delayMs: opts?.delayMs,
+        dedupId: opts?.dedupId
+      });
+      return { id };
+    },
+    async enqueueGroup(name, payloads, opts) {
       if (stopped) {
         throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
       }
+      assertGroupSupport();
       assertKnownTask(name);
-      const data = await validatePayload(name, payload);
-      const meta = registry.get(name);
-      const id = await driver.enqueue(name, data, {
-        delayMs: opts?.delayMs,
-        retries: meta.retries ?? 0,
-        dedupId: opts?.dedupId,
-        // 执行硬限预算透传驱动（pgboss 映射 expireInSeconds）：未声明 timeoutMs 时
-        // 两字段为 undefined，驱动用自身兜底
-        timeoutMs: meta.timeoutMs,
-        graceMs: meta.graceMs
+      if (!Array.isArray(payloads) || payloads.length === 0) {
+        throw new Error(
+          "[faapi] enqueueGroup requires a non-empty payloads array \u2014 a group without members can never settle."
+        );
+      }
+      const onComplete = opts?.onComplete;
+      if (onComplete !== void 0) assertKnownTask(onComplete);
+      const onFailure = opts?.onFailure ?? "run-to-completion";
+      const validated = [];
+      for (const p of payloads) {
+        validated.push(await validatePayload(name, p));
+      }
+      const groupId = opts?.groupId ?? crypto.randomUUID();
+      await driver.groups.create({
+        id: groupId,
+        task: name,
+        total: validated.length,
+        ...onComplete !== void 0 ? { onComplete } : {},
+        onFailure
       });
-      if (!records.has(id)) {
-        records.set(id, {
-          id,
-          name,
-          payload: data,
-          status: "pending",
-          attempts: 0,
-          createdAt: Date.now(),
-          ...opts?.delayMs ? { runAt: Date.now() + opts.delayMs } : {}
+      const jobs = [];
+      for (let i = 0; i < validated.length; i++) {
+        const id = await enqueueCore(name, validated[i], {
+          delayMs: opts?.delayMs,
+          dedupId: GROUP_MEMBER_DEDUP(groupId, i + 1),
+          groupId
         });
+        jobs.push({ id });
       }
-      return { id };
+      await maybeFireCompletion(await driver.groups.get(groupId));
+      return { groupId, jobs };
+    },
+    async getGroup(groupId) {
+      assertGroupSupport();
+      return driver.groups.get(groupId);
     },
     list(name) {
       const snapshot = [];
@@ -9852,6 +10019,7 @@ function createTaskQueue(deps) {
           status: record.status,
           attempts: record.attempts,
           createdAt: record.createdAt,
+          ...record.groupId !== void 0 ? { groupId: record.groupId } : {},
           ...record.result !== void 0 ? { result: record.result } : {},
           ...record.error !== void 0 ? { error: record.error } : {},
           ...record.runAt !== void 0 ? { runAt: record.runAt } : {}
@@ -9871,8 +10039,11 @@ function createTaskQueue(deps) {
       }
       await driver.cancel(name, id);
       const record = records.get(id);
-      if (record) transitionStatus(record, "cancelled");
-      evictFinishedRecords();
+      if (record) {
+        transitionStatus(record, "cancelled");
+        evictFinishedRecords();
+        await settleGroup(record, "cancelled", false);
+      }
     },
     async retry(name, id) {
       if (!driver.retry) {
@@ -9882,7 +10053,18 @@ function createTaskQueue(deps) {
       }
       await driver.retry(name, id);
       const record = records.get(id);
-      if (record) transitionStatus(record, "pending");
+      if (record) {
+        const wasTerminal = TERMINAL_STATUSES.has(record.status);
+        transitionStatus(record, "pending");
+        if (wasTerminal && record.groupId && driver.groups) {
+          await driver.groups.unsettle(record.groupId, record.id).catch((err) => {
+            console.error(
+              `[faapi] task group unsettle failed for "${record.groupId}" (job ${record.id}):`,
+              err
+            );
+          });
+        }
+      }
     },
     async start() {
       if (stopped) {
@@ -9909,7 +10091,7 @@ function createTaskQueue(deps) {
   };
   return queue;
 }
-var TERMINAL_STATUSES, MAX_FINISHED_RECORDS;
+var TERMINAL_STATUSES, GROUP_MEMBER_DEDUP, GROUP_COMPLETION_DEDUP, TASK_CLIENT_METHODS, MAX_FINISHED_RECORDS;
 var init_taskQueue = __esm({
   "src/task/taskQueue.ts"() {
     "use strict";
@@ -9918,6 +10100,17 @@ var init_taskQueue = __esm({
     init_registries();
     init_logger();
     TERMINAL_STATUSES = /* @__PURE__ */ new Set(["done", "failed", "cancelled"]);
+    GROUP_MEMBER_DEDUP = (groupId, index) => `faapi-group:${groupId}:${index}`;
+    GROUP_COMPLETION_DEDUP = (groupId) => `faapi-group:${groupId}:complete`;
+    TASK_CLIENT_METHODS = /* @__PURE__ */ new Set([
+      "enqueue",
+      "enqueueGroup",
+      "list",
+      "listQueued",
+      "cancel",
+      "retry",
+      "getGroup"
+    ]);
     MAX_FINISHED_RECORDS = 1e3;
   }
 });
@@ -10041,7 +10234,7 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
   const upgradeWrappers = [];
   const failures = [];
   if (!declarations || declarations.length === 0) {
-    return { handlerWrappers, upgradeWrappers, failures };
+    return { handlerWrappers, upgradeWrappers };
   }
   const fullCtx = {
     ...ctx,
@@ -10068,7 +10261,7 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
     }
     if (enable === false) continue;
     if (loaded.has(specifier)) {
-      console.warn(`! Plugin already loaded: ${specifier}, skipping`);
+      failures.push({ specifier, reason: "duplicate plugin declaration" });
       continue;
     }
     loaded.add(specifier);
@@ -10089,12 +10282,12 @@ async function loadPlugins(declarations, ctx, rootDir, dist) {
     }
   }
   if (failures.length > 0) {
-    console.error(
+    throw new Error(
       `[faapi] ${failures.length} plugin(s) failed to load:
 ` + failures.map((f) => `  - ${f.specifier}: ${f.reason}`).join("\n")
     );
   }
-  return { handlerWrappers, upgradeWrappers, failures };
+  return { handlerWrappers, upgradeWrappers };
 }
 function resolveLocalPluginSource(specifier, baseDir) {
   const base = path29.isAbsolute(specifier) ? specifier : path29.resolve(baseDir, specifier);
@@ -10428,7 +10621,7 @@ async function createAppBase(options) {
   const taskQueue = createTaskQueue({
     registry: registries.task,
     rootDir,
-    config,
+    config: config ?? {},
     resourcesDir,
     registries: createTaskRegistriesView(registries),
     // 轻量补全通道：进程内路径经 store 惰性读取（插件注册后的活引用）；
@@ -10459,7 +10652,7 @@ async function createAppBase(options) {
     dist,
     cors: config?.cors ?? true,
     onError: config?.lifecycle?.onError,
-    config: config ?? void 0,
+    config,
     wsRoutes,
     middlewares: config?.middlewares,
     injectors: config?.injectors,