@rytass/bpm-core-nestjs-module 0.23.0 → 0.24.0

package/src/lib/workflow-engine/workflow-engine.service.js

@@ -47,10 +47,12 @@ const approval_instance_field_filter_compiler_1 = require("./approval-instance-f
 const approval_instance_filterable_field_policy_1 = require("./approval-instance-filterable-field.policy");
 const text_field_pattern_test_1 = require("./text-field-pattern-test");
 const form_data_fingerprint_1 = require("./form-data-fingerprint");
+const instance_advance_failure_1 = require("./instance-advance-failure");
 const instance_submitter_1 = require("./instance-submitter");
 const task_decision_entity_1 = require("./task-decision.entity");
 const task_candidate_entity_1 = require("./task-candidate.entity");
 const task_entity_1 = require("./task.entity");
+const stuck_approval_instance_query_1 = require("./stuck-approval-instance.query");
 const workflow_engine_enums_1 = require("./workflow-engine.enums");
 const workflow_condition_evaluator_1 = require("./workflow-condition-evaluator");
 const workflow_form_value_1 = require("./workflow-form-value");
@@ -187,6 +189,22 @@ const INACTIVE_MEMBER_NAME_LOCALE = 'zh-Hant-TW';
  * every load of the member screen.
  */
 const INACTIVE_MEMBER_COUNT_CONCURRENCY = 5;
+/**
+ * How many times an `ADVANCE_FAILED` row is tried before giving up. A missed
+ * row hides the instance from the stuck list, and a second try is safe: the
+ * duplicate check runs under the instance lock.
+ */
+const ADVANCE_FAILURE_RECORD_ATTEMPTS = 2;
+// What each way of being skipped writes into the `TOKEN_ADVANCED` payload. The
+// two chain settings that can skip a node share one key.
+const SKIPPED_RUNTIME_TASK_PAYLOADS = {
+    INITIATOR: { skippedByInitiatorExclusion: true },
+    MANAGER_CHAIN_REACHED: { skippedByManagerChainReached: true },
+    NODE_ACTORS: { skippedByNodeActorExclusion: true },
+};
+// Why a chain that continues an earlier one, or skips when its start already
+// qualifies, is refused anywhere task creation did not work its context out.
+const ORG_MANAGER_CHAIN_CONTEXT_REFUSAL = '接續前一段主管鏈、或「起點本人已達簽到職等時略過」，只能在建立簽核任務時使用，此處不支援。';
 /**
  * ADR 27 §4.2: an approver-filled value the provider no longer offers answers
  * 400 with `formDataErrors` naming the field or table cell, `code` kept. Other
@@ -361,6 +379,151 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }, Promise.resolve());
         return result;
     }
+    /**
+     * Runs a public operation whose engine transaction may fail with an
+     * {@link InstanceAdvanceFailure}. The transaction has rolled back by the time
+     * it lands here, so the record is written in a transaction of its own, and
+     * the caller then gets the original error: same class, same message, as if
+     * none of this existed. The wrapper type never leaves this method.
+     */
+    async withAdvanceFailureRecorded(run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (error instanceof instance_advance_failure_1.InstanceAdvanceFailure) {
+                await this.recordAdvanceFailure(error);
+                throw error.originalError;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Writes the `ADVANCE_FAILED` row for a rolled-back attempt, trying again
+     * once if the write fails. If every try fails the failure is logged as an
+     * error with what the row would have held, and swallowed: the caller must
+     * see the error that stopped the case, not the one that stopped its record.
+     * Such an instance is missing from the stuck list, so the log is the only
+     * trace of it.
+     */
+    async recordAdvanceFailure(failure, attempt = 1) {
+        const { context, message } = failure;
+        try {
+            await this.writeAdvanceFailure(failure);
+        }
+        catch (recordError) {
+            const reason = recordError instanceof Error ? recordError.message : 'unknown error';
+            if (attempt < ADVANCE_FAILURE_RECORD_ATTEMPTS) {
+                this.logger.warn(`Could not record ADVANCE_FAILED for instance ${context.instanceId} (attempt ${attempt}), trying again: ${reason}`);
+                return this.recordAdvanceFailure(failure, attempt + 1);
+            }
+            this.logger.error(`Could not record ADVANCE_FAILED for instance ${context.instanceId}; it will not appear in the stuck list: ${reason}`, JSON.stringify({
+                action: context.action,
+                actorMemberId: context.actorMemberId,
+                automatic: context.automatic,
+                kind: context.kind,
+                message,
+                nodeId: context.nodeId,
+                taskId: context.taskId,
+            }));
+        }
+    }
+    /** One try of {@link recordAdvanceFailure}, in a transaction of its own. */
+    async writeAdvanceFailure(failure) {
+        const { context, message } = failure;
+        await this.approvalInstanceRepository.manager.transaction(async (manager) => {
+            // The same per-instance lock every decision takes, so two attempts
+            // failing together cannot both pass the check below and write twice.
+            await manager.query('SELECT pg_advisory_xact_lock(hashtext($1))', [
+                context.instanceId,
+            ]);
+            const unresolved = await this.readUnresolvedAdvanceFailures(manager, context.instanceId);
+            if (unresolved.some((logged) => isSameAdvanceFailure(logged, context, message))) {
+                return;
+            }
+            const activityRepository = manager.getRepository(activity_log_entity_1.ActivityLogEntity);
+            await activityRepository.save(activityRepository.create({
+                actorMemberId: context.actorMemberId,
+                eventType: workflow_engine_enums_1.ActivityLogEventTypeEnum.ADVANCE_FAILED,
+                instanceId: context.instanceId,
+                nodeId: context.nodeId,
+                payload: {
+                    action: context.action,
+                    automatic: context.automatic,
+                    kind: context.kind,
+                    message,
+                    nodeId: context.nodeId,
+                    taskId: context.taskId,
+                },
+                taskId: context.taskId,
+            }));
+        });
+    }
+    /**
+     * The `ADVANCE_FAILED` rows of one instance that still describe how it is
+     * stuck, oldest first. Whether a decision went through is not read from
+     * `TASK_DECIDED`: a countersign leaves one behind from an earlier voter while
+     * the last vote is the one that failed. What counts is whether the situation
+     * the row describes still holds.
+     *
+     * - `DECISION`: the task is still open and the instance is still RUNNING.
+     *   Once the task is done, cancelled, transferred or the instance has ended,
+     *   the case has moved on or been taken over.
+     * - `RESUBMIT`: the instance is still RETURNED and no later
+     *   `INSTANCE_RESUBMITTED` exists.
+     *
+     * The rule itself is `readUnresolvedInstanceFailures` in
+     * `stuck-approval-instance.query.ts`, which also holds the SQL the stuck list
+     * pages with; the two must agree. This is the duplicate check's side.
+     */
+    async readUnresolvedAdvanceFailures(manager, instanceId) {
+        const instance = await manager
+            .getRepository(approval_instance_entity_1.ApprovalInstanceEntity)
+            .findOne({ where: { id: instanceId } });
+        if (!instance) {
+            return [];
+        }
+        const byInstance = await this.readUnresolvedAdvanceFailuresByInstance(manager, [instance]);
+        return byInstance.get(instance.id) ?? [];
+    }
+    /**
+     * {@link readUnresolvedAdvanceFailures} for many instances at once, in two
+     * queries whatever their number: one for their activity rows, one for the
+     * tasks those rows name. Instances with nothing unresolved are absent.
+     */
+    async readUnresolvedAdvanceFailuresByInstance(manager, instances) {
+        if (instances.length === 0) {
+            return new Map();
+        }
+        const logs = await manager.getRepository(activity_log_entity_1.ActivityLogEntity).find({
+            order: { seq: 'ASC' },
+            where: {
+                eventType: (0, typeorm_2.In)([
+                    workflow_engine_enums_1.ActivityLogEventTypeEnum.ADVANCE_FAILED,
+                    workflow_engine_enums_1.ActivityLogEventTypeEnum.INSTANCE_RESUBMITTED,
+                ]),
+                instanceId: (0, typeorm_2.In)(instances.map((instance) => instance.id)),
+            },
+        });
+        const decidedTaskIds = [
+            ...new Set(logs.flatMap((log) => log.eventType === workflow_engine_enums_1.ActivityLogEventTypeEnum.ADVANCE_FAILED &&
+                log.taskId
+                ? [log.taskId]
+                : [])),
+        ];
+        const openTaskIds = new Set(decidedTaskIds.length === 0
+            ? []
+            : (await manager.getRepository(task_entity_1.TaskEntity).find({
+                where: {
+                    id: (0, typeorm_2.In)(decidedTaskIds),
+                    status: (0, typeorm_2.In)([...OPEN_TASK_STATUSES]),
+                },
+            })).map((task) => task.id));
+        return new Map(instances.flatMap((instance) => {
+            const unresolved = (0, stuck_approval_instance_query_1.readUnresolvedInstanceFailures)(instance, logs.filter((log) => log.instanceId === instance.id), openTaskIds);
+            return unresolved.length === 0 ? [] : [[instance.id, unresolved]];
+        }));
+    }
     /**
      * Queues a webhook for after the commit. A manager this service did not open
      * has no queue and no commit it can see, so that webhook goes out on the spot
@@ -746,6 +909,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         });
     }
     async decideTask(input, options = {}) {
+        return this.withAdvanceFailureRecorded(() => this.decideTaskInTransaction(input, options));
+    }
+    async decideTaskInTransaction(input, options) {
         return this.runEngineTransaction(async (manager) => {
             const taskRepository = manager.getRepository(task_entity_1.TaskEntity);
             const taskCandidateRepository = manager.getRepository(task_candidate_entity_1.TaskCandidateEntity);
@@ -1167,6 +1333,18 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 },
                 taskId: completedTask.id,
             }));
+            // What an ADVANCE_FAILED row says if the move to the next stage fails.
+            // An SLA timeout acts as the member `resolveTaskActorMemberId` picked,
+            // who never pressed anything, so `automatic` is what tells them apart.
+            const advanceContext = (action) => ({
+                action,
+                actorMemberId: input.decidedByMemberId,
+                automatic: options.automatic ?? null,
+                instanceId: instance.id,
+                kind: 'DECISION',
+                nodeId: claimedTask.nodeId,
+                taskId: claimedTask.id,
+            });
             // Resolve the recipient's "待簽" notification so its inline 同意/拒絕
             // actions disappear once the task is decided. When the task has ended
             // (rejected / returned, or an approval that completed it), every other
@@ -1201,30 +1379,34 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 if (await this.hasOpenTasksForTokenNode(manager, claimedTask.tokenId, claimedTask.nodeId)) {
                     return decision;
                 }
-                const token = await tokenRepository.findOne({
-                    where: { id: claimedTask.tokenId },
-                });
-                if (!token) {
-                    throw new common_1.NotFoundException(`Workflow token ${claimedTask.tokenId} was not found`);
-                }
-                if (token.status !== workflow_engine_enums_1.WorkflowTokenStatusEnum.WAITING) {
-                    throw new common_1.ConflictException(`Workflow token ${token.id} is not waiting for a task decision`);
-                }
-                const activeToken = await tokenRepository.save({
-                    ...token,
-                    consumedAt: null,
-                    status: workflow_engine_enums_1.WorkflowTokenStatusEnum.ACTIVE,
+                // Everything from here to the next stage is the part that leaves the
+                // case stuck when it fails: the decision rolls back with it.
+                await runInstanceAdvanceStep(advanceContext('APPROVED'), async () => {
+                    const token = await tokenRepository.findOne({
+                        where: { id: claimedTask.tokenId },
+                    });
+                    if (!token) {
+                        throw new common_1.NotFoundException(`Workflow token ${claimedTask.tokenId} was not found`);
+                    }
+                    if (token.status !== workflow_engine_enums_1.WorkflowTokenStatusEnum.WAITING) {
+                        throw new common_1.ConflictException(`Workflow token ${token.id} is not waiting for a task decision`);
+                    }
+                    const activeToken = await tokenRepository.save({
+                        ...token,
+                        consumedAt: null,
+                        status: workflow_engine_enums_1.WorkflowTokenStatusEnum.ACTIVE,
+                    });
+                    await this.dispatchAdhocStageNotifications(manager, instance, claimedTask.nodeId, 'APPROVED');
+                    await this.advanceTokenToOutgoingNodes(manager, instance, activeToken, readWorkflowNodeOrThrow(instance.workflowSnapshot, claimedTask.nodeId));
+                    await this.processRunningInstance(manager, instance);
                 });
-                await this.dispatchAdhocStageNotifications(manager, instance, claimedTask.nodeId, 'APPROVED');
-                await this.advanceTokenToOutgoingNodes(manager, instance, activeToken, readWorkflowNodeOrThrow(instance.workflowSnapshot, claimedTask.nodeId));
-                await this.processRunningInstance(manager, instance);
                 return decision;
             }
             if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED) {
                 return decision;
             }
             if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.RETURNED) {
-                await this.returnInstanceToNode(manager, instance, completedTask, returnToNodeId, decidedAt, input.decidedByMemberId);
+                await runInstanceAdvanceStep(advanceContext('RETURNED'), () => this.returnInstanceToNode(manager, instance, completedTask, returnToNodeId, decidedAt, input.decidedByMemberId));
                 return decision;
             }
             if (await this.handleAdhocPreApprovalRejection(manager, instance, completedTask, decidedAt, decisionComment)) {
@@ -1235,36 +1417,113 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         });
     }
     async cancelApprovalInstance(input) {
+        return this.cancelApprovalInstanceInTransaction({
+            actorMemberId: input.cancelledByMemberId,
+            authorize: (instance) => {
+                if (instance.initiatorMemberId !== input.cancelledByMemberId) {
+                    throw new common_1.ConflictException(`Approval instance ${instance.id} can only be cancelled by its initiator`);
+                }
+            },
+            instanceId: input.instanceId,
+            payload: {
+                comment: input.comment?.trim() || null,
+            },
+        });
+    }
+    /**
+     * Administrator: ends a running or returned instance on the initiator's
+     * behalf, whoever started it. The reason is required; it is recorded as the
+     * comment of the INSTANCE_CANCELLED activity (flagged
+     * `cancelledByAdministrator`, so a host can tell this from the initiator
+     * withdrawing) and sent to the initiator as an in-app notification. An
+     * administrator ending their own instance is not told.
+     *
+     * The notification is written only after the cancellation has committed,
+     * so nobody is told of a cancellation that then rolled back. A failure to
+     * write it is logged and does not undo the cancellation.
+     *
+     * Like the other administrator operations of this service it does not check
+     * who `cancelledByMemberId` is: the GraphQL mutation is guarded by
+     * `@BPMAdminOnly()`, and a host calling this directly must check first. That
+     * member is recorded as the actor of the INSTANCE_CANCELLED activity.
+     */
+    async adminCancelApprovalInstance(input) {
+        const reason = input.reason.trim();
+        // Refused before anything is read, so an empty reason is never mistaken
+        // for a missing instance.
+        if (!reason) {
+            throw new common_1.BadRequestException('A reason is required to cancel an approval instance as an administrator');
+        }
+        const cancelled = await this.cancelApprovalInstanceInTransaction({
+            actorMemberId: input.cancelledByMemberId,
+            authorize: () => undefined,
+            instanceId: input.instanceId,
+            payload: {
+                cancelledByAdministrator: true,
+                comment: reason,
+            },
+        });
+        if (cancelled.initiatorMemberId !== input.cancelledByMemberId) {
+            await this.notifyInitiatorOfAdminCancel(cancelled, reason);
+        }
+        return cancelled;
+    }
+    /**
+     * Tells the initiator, after the commit, that an administrator ended their
+     * instance. Written outside any transaction, so external channels go out
+     * straight away and an observer is told the rows are committed.
+     */
+    async notifyInitiatorOfAdminCancel(instance, reason) {
+        try {
+            await this.notificationService.createAdhocWorkflowNotifications({
+                channels: null,
+                instance,
+                message: `案件「${instance.title}」已由管理員撤銷：${reason}`,
+                payload: {
+                    nodeLabel: '管理員撤銷',
+                    reason,
+                    type: 'INSTANCE_CANCELLED_BY_ADMINISTRATOR',
+                },
+                recipientMemberIds: [instance.initiatorMemberId],
+            });
+        }
+        catch (error) {
+            this.logger.error(`Instance ${instance.id} was cancelled by an administrator, but its initiator ${instance.initiatorMemberId} could not be notified: ${error instanceof Error ? error.message : 'unknown error'}`);
+        }
+    }
+    /**
+     * The cancel transaction both paths share. The order is part of the
+     * contract: read, authorize, check the state, close, record. A non-initiator who tries to withdraw an already
+     * approved instance must keep getting the "initiator" refusal, not
+     * "not cancellable".
+     */
+    async cancelApprovalInstanceInTransaction(cancellation) {
         return this.runEngineTransaction(async (manager) => {
             await manager.query('SELECT pg_advisory_xact_lock(hashtext($1))', [
-                input.instanceId,
+                cancellation.instanceId,
             ]);
             const instanceRepository = manager.getRepository(approval_instance_entity_1.ApprovalInstanceEntity);
             const instance = await instanceRepository.findOne({
-                where: { id: input.instanceId },
+                where: { id: cancellation.instanceId },
             });
             if (!instance) {
-                throw new common_1.NotFoundException(`Approval instance ${input.instanceId} was not found`);
-            }
-            if (instance.initiatorMemberId !== input.cancelledByMemberId) {
-                throw new common_1.ConflictException(`Approval instance ${instance.id} can only be cancelled by its initiator`);
+                throw new common_1.NotFoundException(`Approval instance ${cancellation.instanceId} was not found`);
             }
+            cancellation.authorize(instance);
             if (instance.state !== workflow_engine_enums_1.ApprovalInstanceStateEnum.RUNNING &&
                 instance.state !== workflow_engine_enums_1.ApprovalInstanceStateEnum.RETURNED) {
                 throw new common_1.ConflictException(`Approval instance ${instance.id} is not cancellable`);
             }
             const cancelledInstance = await this.closeInstance(manager, instance, workflow_engine_enums_1.ApprovalInstanceStateEnum.CANCELLED);
             await manager.getRepository(activity_log_entity_1.ActivityLogEntity).save(manager.getRepository(activity_log_entity_1.ActivityLogEntity).create({
-                actorMemberId: input.cancelledByMemberId,
+                actorMemberId: cancellation.actorMemberId,
                 eventType: workflow_engine_enums_1.ActivityLogEventTypeEnum.INSTANCE_CANCELLED,
                 instanceId: instance.id,
                 nodeId: null,
-                payload: {
-                    comment: input.comment?.trim() || null,
-                },
+                payload: cancellation.payload,
                 taskId: null,
             }));
-            await this.recordInstanceEvent(manager, cancelledInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.CANCELLED, 'INSTANCE_CANCELLED', { actorMemberId: input.cancelledByMemberId });
+            await this.recordInstanceEvent(manager, cancelledInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.CANCELLED, 'INSTANCE_CANCELLED', { actorMemberId: cancellation.actorMemberId });
             return cancelledInstance;
         });
     }
@@ -1331,6 +1590,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         return closedInstance;
     }
     async resubmitApprovalInstance(input, authContext) {
+        return this.withAdvanceFailureRecorded(() => this.resubmitApprovalInstanceInTransaction(input, authContext));
+    }
+    async resubmitApprovalInstanceInTransaction(input, authContext) {
         const submittedFormData = parseJsonObject(input.formDataJson, 'formDataJson');
         if (input.endUserSubmission === true) {
             await this.assertEndUserMayResubmit(input.instanceId);
@@ -1437,7 +1699,15 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 },
                 taskId: null,
             }));
-            await this.processRunningInstance(manager, runtimeInstance);
+            await runInstanceAdvanceStep({
+                action: null,
+                actorMemberId: input.initiatorMemberId,
+                automatic: null,
+                instanceId: instance.id,
+                kind: 'RESUBMIT',
+                nodeId: null,
+                taskId: null,
+            }, () => this.processRunningInstance(manager, runtimeInstance));
             const refreshedInstance = await instanceRepository.findOne({
                 where: { id: instance.id },
             });
@@ -1723,7 +1993,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
     }
     async resolveAdhocTaskCandidates(manager, instance, node, label, targetValue) {
         const exclusions = await this.readNodeExclusions(manager, instance, node);
-        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), `${label}「${node.data.label}」`, '簽核人', exclusions.memberIds);
+        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), `${label}「${node.data.label}」`, '簽核人', exclusions.memberIds, null);
         // Ad-hoc approvers are picked by a person, not walked up a manager chain,
         // so the chain's grade rule does not apply to them.
         const delegatedCandidates = await this.delegateResolvedCandidates(manager, instance, node.id, resolvedCandidates, false);
@@ -2131,7 +2401,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             return;
         }
         try {
-            const recipients = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), '臨時通知對象', '通知對象');
+            const recipients = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), '臨時通知對象', '通知對象', [], null);
             await this.notificationService.createAdhocWorkflowNotifications({
                 channels: directive.channels,
                 instance,
@@ -3709,9 +3979,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         });
     }
     async skipNodeByInitiatorExclusion(manager, instance, token, node, skippedBy = 'INITIATOR') {
-        await this.skipNode(manager, instance, token, node, skippedBy === 'NODE_ACTORS'
-            ? { skippedByNodeActorExclusion: true }
-            : { skippedByInitiatorExclusion: true });
+        await this.skipNode(manager, instance, token, node, SKIPPED_RUNTIME_TASK_PAYLOADS[skippedBy]);
     }
     async skipNode(manager, instance, token, node, reason) {
         // A NOTIFY node is an asynchronous branch that may not have an outgoing
@@ -4423,9 +4691,23 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * its own transaction, and reports one result per task. A failing task does
      * not stop the others: a refusal is a REJECTED result, and an unexpected
      * error is reported as REJECTED with UNEXPECTED_ERROR for that task alone.
+     *
+     * `taskIds` narrows the batch to those tasks. Omitted or null keeps every
+     * open task. An empty list throws a BadRequestException before anything is
+     * read: it must never be taken for "all", the write is not reversible. An id
+     * the member does not hold (already moved, instance finished, unknown) yields
+     * no result row and no error; the others still run.
      */
     async reassignMemberTasks(options) {
-        const held = await this.readRunningMemberTasks(options.fromMemberId);
+        const { taskIds } = options;
+        if (taskIds && taskIds.length === 0) {
+            throw new common_1.BadRequestException('taskIds must not be empty: omit it to reassign every open task');
+        }
+        const wanted = taskIds ? new Set(taskIds) : null;
+        const allHeld = await this.readRunningMemberTasks(options.fromMemberId);
+        const held = wanted
+            ? allHeld.filter(({ task }) => wanted.has(task.id))
+            : allHeld;
         return held.reduce(async (previous, { task }) => {
             const results = await previous;
             const result = await this.executeTaskReassignment(task, options).catch((error) => {
@@ -4494,6 +4776,103 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             };
         });
     }
+    /**
+     * The instances that could not move on and still cannot, newest failure
+     * first, one row each, described by their latest unresolved `ADVANCE_FAILED`.
+     *
+     * Which failures are unresolved, the order and the page are decided by the
+     * database (`readStuckFailurePage`, the SQL form of the rule the duplicate
+     * check applies in {@link readUnresolvedAdvanceFailures}); the stuck set is
+     * still evaluated whole before LIMIT applies, but only the page's rows leave
+     * the database. This decorates that page.
+     *
+     * Who has to press again is read now, not copied from the failure: a task
+     * the administrator has reassigned since shows its new holder.
+     * - `DECISION`: the candidates whose seat is PENDING or CLAIMED. A WAITING
+     *   seat of a sequential task is not that member's turn yet. A task without
+     *   a single candidate row is a direct task, held by its assignee.
+     * - `RESUBMIT`: the initiator.
+     */
+    async listStuckApprovalInstances(options = {}) {
+        return this.approvalInstanceRepository.manager.transaction(async (manager) => {
+            const failureIds = await (0, stuck_approval_instance_query_1.readStuckFailurePage)(manager, OPEN_TASK_STATUSES, {
+                limit: normalizePageSize(options.pageSize),
+                offset: readPageOffset(options.page, options.pageSize),
+            });
+            const failures = failureIds.length
+                ? await manager
+                    .getRepository(activity_log_entity_1.ActivityLogEntity)
+                    .find({ where: { id: (0, typeorm_2.In)([...failureIds]) } })
+                : [];
+            const instances = failures.length
+                ? await manager.getRepository(approval_instance_entity_1.ApprovalInstanceEntity).find({
+                    where: {
+                        id: (0, typeorm_2.In)([
+                            ...new Set(failures.map((failure) => failure.instanceId)),
+                        ]),
+                    },
+                })
+                : [];
+            const failureById = new Map(failures.map((failure) => [
+                failure.id,
+                failure,
+            ]));
+            const instanceById = new Map(instances.map((instance) => [
+                instance.id,
+                instance,
+            ]));
+            // `find` does not keep the order of the ids; the page's order is the
+            // database's.
+            const stuck = failureIds.flatMap((failureId) => {
+                const failure = failureById.get(failureId);
+                const instance = failure && instanceById.get(failure.instanceId);
+                return failure && instance ? [{ failure, instance }] : [];
+            });
+            if (stuck.length === 0) {
+                return [];
+            }
+            const taskIds = [
+                ...new Set(stuck.flatMap(({ failure }) => failure.taskId ? [failure.taskId] : [])),
+            ];
+            const tasks = taskIds.length
+                ? await manager
+                    .getRepository(task_entity_1.TaskEntity)
+                    .find({ where: { id: (0, typeorm_2.In)(taskIds) } })
+                : [];
+            const candidates = taskIds.length
+                ? await manager.getRepository(task_candidate_entity_1.TaskCandidateEntity).find({
+                    order: {
+                        sequence: { direction: 'ASC', nulls: 'LAST' },
+                        createdAt: 'ASC',
+                        id: 'ASC',
+                    },
+                    where: { taskId: (0, typeorm_2.In)(taskIds) },
+                })
+                : [];
+            const templates = await manager
+                .getRepository(approval_template_entity_1.ApprovalTemplateEntity)
+                .find({
+                where: {
+                    id: (0, typeorm_2.In)([
+                        ...new Set(stuck.map(({ instance }) => instance.templateId)),
+                    ]),
+                },
+            });
+            const templateNameById = new Map(templates.map((template) => [
+                template.id,
+                template.name,
+            ]));
+            return stuck.map((candidate) => toStuckApprovalInstanceRecord(candidate, {
+                candidates,
+                tasks,
+                templateNameById,
+            }));
+        });
+    }
+    /** How many instances {@link listStuckApprovalInstances} pages through. */
+    async countStuckApprovalInstances() {
+        return this.approvalInstanceRepository.manager.transaction(async (manager) => (0, stuck_approval_instance_query_1.countStuckInstances)(manager, OPEN_TASK_STATUSES));
+    }
     /**
      * Deactivated members who still hold open tasks, so an administrator can find
      * them: a deactivated member no longer shows up in the member search.
@@ -4921,7 +5300,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * Resolves who gets the node's task. A {@link SkippedRuntimeTask} means the
      * node asked to be skipped (`excludeInitiator.whenEmpty` or
      * `excludeNodeActors.whenEmpty` = SKIP_NODE) because everyone left was kept
-     * out: the sole caller creates no task and advances the token instead.
+     * out, or its manager chain found the level it asks for already reached
+     * (`skipWhenStartReached`, or an earlier stage it continues): the sole
+     * caller creates no task and advances the token instead.
      *
      * With both exclusions set the initiator rule runs first. When it alone
      * leaves nobody, `excludeInitiator.whenEmpty` decides; when it leaves
@@ -4930,8 +5311,14 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      */
     async resolveRuntimeTaskCandidates(manager, instance, node) {
         const label = `簽核節點「${node.data.label}」`;
+        // Worked out before anything else because it can end the node: a chain
+        // that needs nobody more is skipped without resolving or excluding anyone.
+        const chainContext = await this.resolveOrgManagerChainContext(manager, instance, node, label);
+        if (chainContext?.skipped) {
+            return { skippedBy: 'MANAGER_CHAIN_REACHED' };
+        }
         const exclusions = await this.readNodeExclusions(manager, instance, node);
-        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, node.data.approverResolver, label, '簽核人', exclusions.memberIds);
+        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, node.data.approverResolver, label, '簽核人', exclusions.memberIds, chainContext);
         const delegatedCandidates = await this.delegateResolvedCandidates(manager, instance, node.id, resolvedCandidates, isOrgManagerChainNode(node));
         const hasExclusion = hasSeatExclusion(node);
         const hasSubmitter = (0, instance_submitter_1.readDistinctSubmitterMemberId)(instance) !== null;
@@ -4971,6 +5358,136 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 ? `${label} 無法建立待簽任務：解析出的簽核人只剩申請人或代為送出此單的人（含委派後的代理人），且此節點不允許申請人或代送人簽核。`
                 : `${label} 無法建立待簽任務：解析出的簽核人只剩申請人本人（含委派後的代理人），且此節點不允許申請人自簽。`);
     }
+    /**
+     * What the walk of `node`'s manager chain has to know first, or `null`
+     * for a node that is not a manager chain using one of the two settings that
+     * need it (continuing an earlier chain, or skipping when the start already
+     * qualifies); such a node is resolved exactly as before.
+     *
+     * The settings are checked again here, since the instance runs on its own
+     * snapshot of the definition and a definition from another build can carry
+     * a shape this one never published. A setting that does not hold throws a
+     * {@link ConflictException} naming the node.
+     *
+     * `skipped` is set when the level the chain asks for is already there: the
+     * start person's own level for `skipWhenStartReached`, the level the earlier
+     * stage got a signature from for a continuation.
+     */
+    async resolveOrgManagerChainContext(manager, instance, node, label) {
+        const resolver = node.data.approverResolver;
+        if (resolver.type !== 'ORG_MANAGER_CHAIN' ||
+            !usesOrgManagerChainSettings(resolver)) {
+            return null;
+        }
+        const shapeIssue = (0, workflow_graph_1.readOrgManagerChainIssue)(resolver, '簽核節點');
+        if (shapeIssue !== null) {
+            throw new common_1.ConflictException(`${label} 無法建立待簽任務：${shapeIssue}`);
+        }
+        if (!(0, workflow_1.isOrgManagerChainContinuation)(resolver)) {
+            return {
+                continuation: null,
+                skipped: await this.isOrgManagerChainStartLevelReached(manager, instance, resolver, label),
+            };
+        }
+        const found = readChainContinuationSource(instance.workflowSnapshot, node.id, resolver);
+        if ('issue' in found) {
+            throw new common_1.ConflictException(`${label} 無法建立待簽任務：${found.issue}`);
+        }
+        // The earlier stage's own start, so both stages climb the same line.
+        const start = await this.resolveOrgManagerChainStart(manager, instance, found.source, label, '簽核人');
+        const reachedLevel = await this.readChainStageReachedLevel(manager, instance, found.sourceId);
+        return {
+            continuation: { reachedLevel, start },
+            skipped: reachedLevel !== null && reachedLevel >= resolver.minPositionLevel,
+        };
+    }
+    /**
+     * `skipWhenStartReached`: whether the person the chain starts from already
+     * holds a position level of `minPositionLevel` or more today. No start
+     * person, or one without a graded position, reads as "not reached" so the
+     * chain is walked as usual.
+     */
+    async isOrgManagerChainStartLevelReached(manager, instance, resolver, label) {
+        const start = await this.resolveOrgManagerChainStart(manager, instance, resolver, label, '簽核人');
+        if (start.memberId === null) {
+            return false;
+        }
+        const level = await this.readMemberPositionLevel(manager, start.memberId, this.readOrganizationToday());
+        return level !== null && level >= resolver.minPositionLevel;
+    }
+    /**
+     * The position level the manager-chain stage `stageNodeId` actually got a
+     * signature from in its latest round (`T`), or `null` when none counts.
+     *
+     * - A stage whose latest round was a skip for `skippedByManagerChainReached`
+     *   got nobody to sign, so its older approvals do not count: `null`.
+     * - Otherwise the people who really approved its latest batch
+     *   ({@link readNodeActorApprovals}: no ad-hoc countersign, no SLA
+     *   auto-approval), each at the level they held on the day they approved.
+     *   `Position.level` has no history, but memberships are dated, so a
+     *   promotion that took effect after the approval does not raise `T`. The day
+     *   is the organisation's, the same one "today" is.
+     *
+     * The people counted are those who pressed approve, delegates and transfer
+     * receivers included, not the seat they sat in.
+     */
+    async readChainStageReachedLevel(manager, instance, stageNodeId) {
+        if (await this.wasChainStageSkippedLastRound(manager, instance, stageNodeId)) {
+            return null;
+        }
+        const approvals = (await this.readNodeActorApprovals(manager, instance, [stageNodeId])).map((decision) => ({
+            date: (0, organization_time_zone_1.formatDateOnlyInTimeZone)(decision.decidedAt, this.organizationTimeZone),
+            memberId: decision.decidedByMemberId,
+        }));
+        const levelGroups = await Promise.all(uniqueTexts(approvals.map((approval) => approval.date)).map(async (date) => [
+            ...(await this.readMemberPositionLevels(manager, approvals
+                .filter((approval) => approval.date === date)
+                .map((approval) => approval.memberId), date)).values(),
+        ]));
+        const levels = levelGroups
+            .flat()
+            .filter((level) => level !== null);
+        return levels.length === 0 ? null : Math.max(...levels);
+    }
+    /**
+     * Whether the latest thing that happened to the stage `stageNodeId` was a
+     * skip for `skippedByManagerChainReached`, rather than a task being made for
+     * it: the newest such `TOKEN_ADVANCED` is newer than the newest
+     * `TASK_CREATED` of one of the stage's own (non-ad-hoc) tasks. Newer is
+     * decided by the log's `seq` (the order the database wrote the rows in;
+     * `created_at` is the transaction start and ties within one transaction).
+     *
+     * The `TASK_CREATED` payload does not say whether its task is ad-hoc, so the
+     * task is looked up by the id the log carries.
+     */
+    async wasChainStageSkippedLastRound(manager, instance, stageNodeId) {
+        const [logs, stageTasks] = await Promise.all([
+            manager.getRepository(activity_log_entity_1.ActivityLogEntity).find({
+                where: {
+                    eventType: (0, typeorm_2.In)([
+                        workflow_engine_enums_1.ActivityLogEventTypeEnum.TOKEN_ADVANCED,
+                        workflow_engine_enums_1.ActivityLogEventTypeEnum.TASK_CREATED,
+                    ]),
+                    instanceId: instance.id,
+                    nodeId: stageNodeId,
+                },
+            }),
+            manager.getRepository(task_entity_1.TaskEntity).find({
+                where: { instanceId: instance.id, isAdhoc: false, nodeId: stageNodeId },
+            }),
+        ]);
+        const stageTaskIds = new Set(stageTasks.map((task) => task.id));
+        const newestSeq = (matching) => matching.reduce((newest, log) => {
+            const seq = BigInt(log.seq);
+            return newest === null || seq > newest ? seq : newest;
+        }, null);
+        const skippedSeq = newestSeq(logs.filter((log) => log.eventType === workflow_engine_enums_1.ActivityLogEventTypeEnum.TOKEN_ADVANCED &&
+            log.payload['skippedByManagerChainReached'] === true));
+        const createdSeq = newestSeq(logs.filter((log) => log.eventType === workflow_engine_enums_1.ActivityLogEventTypeEnum.TASK_CREATED &&
+            log.taskId !== null &&
+            stageTaskIds.has(log.taskId)));
+        return (skippedSeq !== null && (createdSeq === null || skippedSeq > createdSeq));
+    }
     /**
      * Everyone `node` keeps out of its approvers, per rule: the initiator and
      * the submitter for `excludeInitiator`, and everyone who actually approved
@@ -5185,15 +5702,18 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             ? requiredLevel
             : null;
     }
-    async resolveApproverResolver(manager, instance, resolver, label, subject = '簽核人', skippedChainMemberIds = []) {
-        const memberIds = await this.resolveApproverMemberIds(manager, instance, resolver, label, subject, skippedChainMemberIds);
+    async resolveApproverResolver(manager, instance, resolver, label, subject, skippedChainMemberIds, 
+    // Required, so a new entry point has to say it has none: only task
+    // creation works one out, and a chain that needs it refuses without it.
+    chainContext) {
+        const memberIds = await this.resolveApproverMemberIds(manager, instance, resolver, label, subject, skippedChainMemberIds, chainContext);
         return memberIds.map((memberId) => ({
             memberId,
             sourceType: resolver.type,
         }));
     }
     /** The member ids `resolver` routes to; every source type, one branch each. */
-    async resolveApproverMemberIds(manager, instance, resolver, label, subject, skippedChainMemberIds) {
+    async resolveApproverMemberIds(manager, instance, resolver, label, subject, skippedChainMemberIds, chainContext) {
         if (resolver.type === 'DIRECT') {
             return readMemberIdsFromValue(resolver.memberIds, label, subject);
         }
@@ -5216,7 +5736,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             return this.resolveOrgUnitManagerCandidates(manager, instance, resolver.orgUnitId, resolver.fallback, label, resolver.preferClosestOrgUnit === true, subject);
         }
         if (resolver.type === 'ORG_MANAGER_CHAIN') {
-            return this.resolveOrgManagerChainCandidates(manager, instance, resolver, label, subject, skippedChainMemberIds);
+            return this.resolveOrgManagerChainCandidates(manager, instance, resolver, label, subject, skippedChainMemberIds, chainContext);
         }
         if (resolver.type === 'ORG_MANAGER') {
             return this.resolveInitiatorManagerCandidates(manager, instance, resolver.levelsUp, resolver.fallback, label, resolver.preferClosestOrgUnit === true, subject);
@@ -5416,11 +5936,26 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * past without joining the chain or counting as the stopping point, and so
      * are managers below `startPositionLevel`, until the first one at or above
      * it starts the chain.
+     *
+     * A chain that continues an earlier stage climbs from that stage's start and
+     * walks past every manager whose level is not above the one the stage got a
+     * signature from, as if that level were the last one already added. Both it
+     * and a chain that skips when its start already qualifies are only walked
+     * with the `chainContext` task creation worked out; without one they are
+     * refused, which keeps every other entry point (a notify node's recipients,
+     * for one) from reading them as an ordinary chain.
      */
-    async resolveOrgManagerChainCandidates(manager, instance, resolver, label, subject, skippedMemberIds) {
+    async resolveOrgManagerChainCandidates(manager, instance, resolver, label, subject, skippedMemberIds, chainContext) {
         const { fallback, minPositionLevel } = resolver;
         const startPositionLevel = (0, workflow_1.readOrgManagerChainStartPositionLevel)(resolver);
-        const start = await this.resolveOrgManagerChainStart(manager, instance, resolver, label, subject);
+        const continuation = chainContext?.continuation ?? null;
+        if (usesOrgManagerChainSettings(resolver) &&
+            (!chainContext ||
+                ((0, workflow_1.isOrgManagerChainContinuation)(resolver) && continuation === null))) {
+            throw new common_1.ConflictException(`${label} ${subject === '通知對象' ? '無法建立通知' : '無法建立待簽任務'}：${ORG_MANAGER_CHAIN_CONTEXT_REFUSAL}`);
+        }
+        const start = continuation?.start ??
+            (await this.resolveOrgManagerChainStart(manager, instance, resolver, label, subject));
         // Nobody to climb from: the same "no manager" path as a chain whose walk
         // finds nobody, so the fallback decides.
         if (start.memberId === null) {
@@ -5430,7 +5965,10 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         const visitedMemberIds = new Set([start.memberId]);
         const chain = [];
         let currentMemberId = start.memberId;
-        let lastAddedLevel = null;
+        // A continuation starts out as if the level its earlier stage got a
+        // signature from were the last one added: managers at or below it are
+        // walked past, so only those above it are asked.
+        let lastAddedLevel = continuation?.reachedLevel ?? null;
         for (let hop = 0; hop < ORG_MANAGER_CHAIN_MAX_HOPS; hop += 1) {
             // A chain is a single path, so it always uses closest-org-unit semantics
             // (merging ancestor-unit rules could only produce ties). The member is
@@ -5515,6 +6053,12 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         if (subject === '通知對象') {
             throw new common_1.ConflictException(`${label} ${failure}：知會節點的主管鏈只能從發起人開始。`);
         }
+        // The start of a continuation is its earlier stage's, which task creation
+        // hands over already resolved; asking for it here is a mistake of the
+        // caller, not a start to climb from.
+        if (startFrom.type === 'CHAIN_CONTINUATION') {
+            throw new common_1.ConflictException(`${label} ${failure}：${ORG_MANAGER_CHAIN_CONTEXT_REFUSAL}`);
+        }
         if (startFrom.type === 'FORM_MEMBER') {
             const source = `依表單欄位「${startFrom.formPath}」`;
             const pickedMemberIds = findMemberIdsInValue(readValueAtPath(instance.formData, startFrom.formPath));
@@ -5898,7 +6442,10 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         const recipients = (0, workflow_graph_1.isNotifyRecipientsEmpty)(action.recipients) &&
             (0, workflow_graph_1.readNotifyWebhookTargets)(action).length > 0
             ? []
-            : await this.resolveApproverResolver(manager, instance, action.recipients, `知會節點「${node.data.label}」`, '通知對象');
+            : await this.resolveApproverResolver(manager, instance, action.recipients, `知會節點「${node.data.label}」`, '通知對象', [], 
+            // A notify node has no task to build the context: a chain that
+            // needs one is refused (publish lint forbids it here already).
+            null);
         const recipientMemberIds = uniqueTexts(recipients.map((recipient) => recipient.memberId));
         await this.notificationService.createServiceTaskNotifications({
             instance,
@@ -6846,6 +7393,92 @@ function readReturnResubmitStrategyFromPayload(payload) {
         ? 'FROM_RETURN_POINT'
         : 'RESTART';
 }
+/**
+ * Whether a recorded failure is the one a new attempt would write again: same
+ * kind and key, same reason. A decision is keyed by task, actor and action, so
+ * the votes of a countersign each keep their own row; a resubmission has one
+ * key per instance. The same actor failing for a different reason is news, so
+ * the message is part of the match.
+ */
+function isSameAdvanceFailure(logged, context, message) {
+    if (readStringPayloadValue(logged.payload, 'kind') !== context.kind ||
+        logged.payload['message'] !== message) {
+        return false;
+    }
+    return (context.kind === 'RESUBMIT' ||
+        (logged.taskId === context.taskId &&
+            logged.actorMemberId === context.actorMemberId &&
+            readStringPayloadValue(logged.payload, 'action') === context.action));
+}
+/**
+ * Runs the step that moves an instance on and, when it fails with an error an
+ * operator is meant to read (an `HttpException` below 500), hands it on as an
+ * {@link InstanceAdvanceFailure} so the public method can record it once the
+ * transaction has rolled back. Everything else passes through untouched: a 5xx
+ * is usually a hiccup that retrying clears, and a plain `Error` may carry SQL.
+ *
+ * Used at the three call sites only. `processRunningInstance` and
+ * `returnInstanceToNode` stay unwrapped because submit and the administrator's
+ * re-run call them too, and they must keep throwing the original class.
+ */
+async function runInstanceAdvanceStep(context, step) {
+    try {
+        return await step();
+    }
+    catch (error) {
+        if (error instanceof common_1.HttpException && error.getStatus() < 500) {
+            throw new instance_advance_failure_1.InstanceAdvanceFailure(error, context);
+        }
+        throw error;
+    }
+}
+function toStuckApprovalInstanceRecord({ failure, instance }, lookup) {
+    const isResubmit = readStringPayloadValue(failure.payload, 'kind') === 'RESUBMIT';
+    const taskId = isResubmit ? null : failure.taskId;
+    const nodeId = isResubmit ? null : failure.nodeId;
+    const message = failure.payload['message'];
+    return {
+        automatic: failure.payload['automatic'] === SLA_AUTO_APPROVE_MARK
+            ? SLA_AUTO_APPROVE_MARK
+            : null,
+        failedActorMemberId: failure.actorMemberId,
+        failedAt: failure.createdAt,
+        initiatorMemberId: instance.initiatorMemberId,
+        instanceId: instance.id,
+        instanceTitle: instance.title,
+        kind: isResubmit
+            ? workflow_engine_enums_1.StuckApprovalInstanceKindEnum.RESUBMIT
+            : workflow_engine_enums_1.StuckApprovalInstanceKindEnum.DECISION,
+        message: typeof message === 'string' ? message : '',
+        nodeId,
+        nodeLabel: nodeId
+            ? readWorkflowNodeLabel(instance.workflowSnapshot, nodeId)
+            : null,
+        pendingActorMemberIds: taskId === null
+            ? [instance.initiatorMemberId]
+            : readTaskHolderMemberIds(lookup.tasks.find((task) => task.id === taskId) ?? null, lookup.candidates.filter((candidate) => candidate.taskId === taskId)),
+        taskId,
+        templateId: instance.templateId,
+        templateName: lookup.templateNameById.get(instance.templateId) ?? null,
+    };
+}
+/**
+ * The members who can press a task's button now: a PENDING or CLAIMED seat,
+ * each member once. A WAITING seat of a sequential task is not that member's
+ * turn yet. A task with no candidate row at all is a direct task, held by its
+ * assignee, as the reassignment check reads it.
+ */
+function readTaskHolderMemberIds(task, candidates) {
+    if (candidates.length === 0) {
+        return task?.assigneeMemberId ? [task.assigneeMemberId] : [];
+    }
+    return [
+        ...new Set(candidates
+            .filter((candidate) => candidate.status === workflow_engine_enums_1.TaskCandidateStatusEnum.PENDING ||
+            candidate.status === workflow_engine_enums_1.TaskCandidateStatusEnum.CLAIMED)
+            .map((candidate) => candidate.memberId)),
+    ];
+}
 function readStringPayloadValue(payload, key) {
     const value = payload[key];
     return typeof value === 'string' && value.trim() ? value.trim() : null;
@@ -6998,6 +7631,73 @@ function readInitiatorAndSubmitter(instance) {
 function isOrgManagerChainNode(node) {
     return node.data.approverResolver.type === 'ORG_MANAGER_CHAIN';
 }
+/**
+ * Whether a manager chain uses one of the two settings that need the context
+ * task creation works out first: it continues an earlier chain, or
+ * `skipWhenStartReached` is anything but absent, `null` or `false` (a value
+ * that is not a boolean is "used" too, so the shape check can refuse it
+ * instead of the chain being walked as if it were absent).
+ */
+function usesOrgManagerChainSettings(resolver) {
+    const skipWhenStartReached = resolver.skipWhenStartReached;
+    return ((0, workflow_1.isOrgManagerChainContinuation)(resolver) ||
+        (skipWhenStartReached !== undefined &&
+            skipWhenStartReached !== null &&
+            skipWhenStartReached !== false));
+}
+/**
+ * The manager-chain stage a continuing chain (`nodeId`, whose resolver is
+ * `resolver`) continues, or the first reason it cannot: it is missing, not a
+ * user task, not a manager chain, itself a continuation (stages are not
+ * chained more than once), started from something that can change while the
+ * stage's approvals stay (a form field, or a start this build does not know),
+ * or asks for a level at or below this chain's own, which would skip this
+ * chain every time. The same rules the publish lint applies to the stage;
+ * where the stage sits in the graph is only checked there.
+ */
+function readChainContinuationSource(workflow, nodeId, resolver) {
+    const sourceId = resolver.startFrom.nodeId;
+    const source = workflow.nodes.find((candidate) => candidate.id === sourceId);
+    const nameOf = (id) => `「${readWorkflowNodeLabel(workflow, id) ?? id}」`;
+    if (source === undefined) {
+        return { issue: `接續的前一段主管鏈「${sourceId}」不存在。` };
+    }
+    if (source.type !== 'userTask') {
+        return { issue: `接續的前一段主管鏈 ${nameOf(sourceId)} 不是簽核關卡。` };
+    }
+    const sourceResolver = source.data.approverResolver;
+    if (sourceResolver?.type !== 'ORG_MANAGER_CHAIN') {
+        return {
+            issue: `接續的前一段 ${nameOf(sourceId)} 的簽核來源不是「沿主管鏈簽核」。`,
+        };
+    }
+    if ((0, workflow_1.isOrgManagerChainContinuation)(sourceResolver)) {
+        return {
+            issue: `接續的前一段主管鏈 ${nameOf(sourceId)} 本身也是接續型主管鏈，不支援多段串接。`,
+        };
+    }
+    const sourceStart = sourceResolver.startFrom;
+    const sourceStartType = typeof sourceStart === 'object' && sourceStart !== null
+        ? sourceStart.type
+        : undefined;
+    if (sourceStart !== undefined &&
+        sourceStart !== null &&
+        sourceStartType !== 'INITIATOR' &&
+        sourceStartType !== 'NODE_ACTOR') {
+        return {
+            issue: `接續的前一段主管鏈 ${nameOf(sourceId)} 的起點只能是申請人或前面關卡的簽核者，不能是表單欄位或其他起點。`,
+        };
+    }
+    const sourceLevel = sourceResolver.minPositionLevel;
+    if (typeof sourceLevel === 'number' &&
+        Number.isInteger(sourceLevel) &&
+        resolver.minPositionLevel <= sourceLevel) {
+        return {
+            issue: `接續關卡 ${nameOf(nodeId)} 的職等門檻（${resolver.minPositionLevel}）必須高於前一段主管鏈 ${nameOf(sourceId)} 的職等門檻（${sourceLevel}）；否則前一段只要簽到自己的職等，這一關就一定被略過。`,
+        };
+    }
+    return { source: sourceResolver, sourceId };
+}
 // Candidates of a manager-chain node that came from the chain (or replaced the
 // excluded initiator's seat); ad-hoc approvers are chosen by a person instead.
 function isGradeGatedCandidate(node, sourceType) {